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 6 - Installation and Configuration Topics======
==== AGWHOST ====
<code>AGWHOST(6)              XROUTER REFERENCE MANUAL             27/9/2023

</code> **NAME** <code>
        AGWHOST -- AGW Application Support.

</code> **DESCRIPTION** <code>
        XRouter provides an AGW TCP host mode interface, allowing apps
        such as UI-View, which would normally use AGW Packet Engine,
        (AGWPE) to use XRouter instead. 

        You should not confuse this with XRouter's AGW *interface*,
        which allows XRouter to interface with "real" AGWPE. The
        following diagram attempts to explain the difference:


                  UI-View etc         <-- Application expecting AGW
             .--------------------.
             | (AGWHOST Emulator) |   <-- App interacts with this
             |                    |
             |      XRouter       |
             |                    |
             |  (AGW interface)   |   <-- Interacts with AGWPE
             |--------------------|
             |  AGW Packet Engine |
             '--------------------'
                Soundcards etc.       <-- Hardware supported by AGW


        There are two ways for an application to interact with AGW
        Packet Engine, one of which is TCP host mode, which normally
        uses TCP port 8000. This is the only mode which XRouter
        emulates.

        Since "real" AGW uses TCP port 8000, XRouter's AGW emulation
        port also defaults to 8000. This can be changed using the
        AGWPORT directive in the GLOBAL section of XROUTER.CFG. You
        might need to do this if you are running AGWPE on the same
        machine. e.g.

            AGWPORT=8001

        Whether or not XRouter requires the applications to send a
        password is controlled by entries in ACCESS.SYS. 

        The following entry allows computers on the LAN to access
        XRouter without a password:

            192.168.0.0/24  1


        AGW host support has so far been tested with:

            - UIView
            - AGWTerminal

        The emulator reports its version number as 2000.15

</code> **SEE ALSO** <code>
        ACCESS.SYS(8)  -- TCP Access Control File.
        AGW-IFACE(6)   -- AGW Packet Engine Interface.
        AGWPORT(7)     -- TCP Port for AGW Emulator.
        XROUTER.CFG(8) -- Main Configuration File.

</code>
----
==== AGW-IFACE ====
<code>AGW-IFACE(6)          XROUTER REFERENCE MANUAL                27/9/2023
</code> **NAME** <code>
        AGW-IFACE -- AGW Packet Engine Interface.

</code> **DESCRIPTION** <code>
        SV2AGW's Packet Engine (commonly known as AGWPE) is a Windows
        program which manages packet radio hardware and provides AX25
        services to other applications via a TCP/IP API (Application
        Programming Interface).

        The API has been adopted by a number of other systems, some of
        which run on Linux, including Direwolf, and XRouter itself. 

        An AGW interface allows you to use any AGW compatible program
        "underneath" XRouter to manage the hardware, and to provide 
        access to hardware not directly supported by XRouter (e.g.
        sound cards).

        You should not confuse this with XRouter's AGWHOST *emulator*,
        which is provided to support apps which expect to see AGWPE.
        The following diagram attempts to explain the difference:


                  UI-View etc         <-- Application expecting AGW
             .--------------------.
             | (AGWHOST Emulator) |   <-- App interacts with this
             |                    |
             |      XRouter       |
             |                    |
             |  (AGW interface)   |   <-- Interacts with AGWPE
             |--------------------|
             |  AGW Packet Engine |
             '--------------------'
                Soundcards etc.       <-- Hardware supported by AGW

          
        The AGW interface communicates with AGWPE's TCP/IP host
        interface, normally using TCP port 8000. XRouter always uses
        the Linux TCP/IP stack for this connection.

        The AGW Packet engine may be located on the same PC or on a
        different PC, which could be anywhere in the world. Thus you
        could for example have a node in your shack whose RF ports
        are remotely located on a nice hilltop! Or you could remotely
        locate one of your ports to prevent desense etc.

        You may configure more than one AGW interface, provided that
        each copy of AGWPE uses a different IP address/TCP port pair.
        A possible use would be a node which has its RF ports located
        on several different hilltops.


        Configuring the INTERFACE
        ~~~~~~~~~~~~~~~~~~~~~~~~~  
        An AGW interface is specified like this:

            INTERFACE=1              ; Change to suit yourself
                TYPE=AGW
                IOADDR=192.168.0.76  ; AGWPE IP (Default=localhost)
                INTNUM=8001          ; AGWPE TCP port (Default=8000)
                MTU=256
                CONFIG=MyAgwPass     ; Password for AGWPE
            ENDINTERFACE

        Note that IOADDR, INTNUM and CONFIG are all optional, and are
        only needed if you want to change the defaults.

        IOADDR and INTNUM don't have the usual meaning. Instead they
        are used to specify the IP address and TCP port number used
        to communicate with AGWPE.
 
        If you don't specify IOADDR, it defaults to 127.0.0.1, which
        is the same computer as XRouter is on. If AGWPE is on a
        different computer to XRouter, you need to enter its IP
        address here.

        If you don't specify INTNUM, it defaults to 8000, which is the
        default AGW host port. Note that XRouter's AGWHOST emulator
        also defaults to this TCP port, so if you wish to leave AGWPE
        on port 8000 you must disable or reassign AGWPORT in
        XROUTER.CFG.

        If you don't specify CONFIG, XRouter won't "authorise" with
        AGW. Authorisation is not usually required if you're using
        XRouter and AGWPE on the same computer.  You can adjust the
        requirement for authorisation in AGWPE's setup.

        If CONFIG is used, the "username" sent to AGWPE is the
        NODECALL and the "password" is the string specified by CONFIG.


        Configuring the PORTs
        ~~~~~~~~~~~~~~~~~~~~~
        An AGWPE interface can support 16 PORTs, which are declared
        in the usual way, each PORT using a different CHANNEL on the
        INTERFACE - for example:

            PORT=1
                  ID=AGW Port 1
                  INTERFACENUM=1
                  CHANNEL=A
            ENDPORT

            PORT=2
                  ID=Agw Port 2
                  INTERFACENUM=1
                  CHANNEL=B
            ENDPORT


        Configuring AGWPE
        ~~~~~~~~~~~~~~~~~
        - is currently beyond the scope of this page. Please refer to
        the documentation supplied with AGWPE


</code> **SEE ALSO** <code>
        AGWHOST(6)     -- AGW Hostmode Emulator
        AGWPORT(7)     -- TCP Port for AGW Emulator.
        IFACES(6)      -- Interfaces in XRouter.
        PORTS(6)       -- Ports in XRouter.
        XROUTER.CFG(8) -- Main Configuration File.

</code>
----
==== ASYNC-IFACE ====
<code>ASYNC-IFACE(6)        XROUTER REFERENCE MANUAL                23/9/2023
</code> **NAME** <code>
        ASYNC -- Interface Type "ASYNC"
 
</code> **DESCRIPTION** <code>
        The ASYNC interface type specifies an asynchronous character
        by character interface, such as RS232 or a pseudo-TTY.

        It is so-called because individual characters are sent and
        received asynchronously, either singly or in random sized
        bunches, rather than in synchronism with a clock signal.

        In XRouter this usually means USB-to-Serial adaptors which
        appear as /dev/ttyUSB0 etc.

        A typical ASYNC interface would be defined thus:

        INTERFACE=1
                TYPE=ASYNC
                ID=Multidrop KISS TNCs
                COM=/dev/ttyUSB1
                SPEED=9600
                PROTOCOL=KISS
                KISSOPTIONS=POLLED,CHECKSUM,ACKMODE
                MTU=256
                FLOW=0
        ENDINTERFACE

        TYPE, COM, SPEED, PROTOCOL and MTU are mandatory.

        ID is an optional plain text string which identifies the
        interface on various displays. Keep it concise. 20 characters
        max.

        COM is the serial device name, e.g. "/dev/tty0". COM=0 is a
        "dummy" device which reads and writes nothing. It can be used
        to "park" interfaces when not in use.

        SPEED is the baud rate used on the interface. Don't include a
        comma, e.g use "9600" not "9,600". The range of supported baud
        rates depends on the device.

        PROTOCOL is the protocol to use on the interface:

             ASCII    - Remote consoles (TTY)
             DEDHOST  - DEDHOST emulation
             KISS     - For driving KISS TNCs or wired links.
             MODEM    - Hayes compatible PSTN modem.
             NETROM   - Netrom backend serial link.
             PPP      - Point to Point Protocol (TCP/IP over RS232)
             SLIP     - Serial Line Internet Protocol (ditto)
             TNC2     - TNC2 emulation.

             (see PROTOCOL(7) for more detail)

        MTU is the "Maximum Transmission Unit". This specifies the
        maximum size for the data portion of an IP packet transmitted
        on the interface.

        Datagrams are sized or fragmented according to the MTU of the
        interface on which they are transmitted.

        XRouter allows MTU's up to 1500 bytes, but setting MTU over
        256 is not recommended on AX25 ports, because the buffer size
        on TNC-based nodes is usually only big enough for a 256-byte
        data field.

        FLOW optionally specifies the flow control options:

             0 = No flow control
             1 = Hardware (RTS/CTS) flow control
             2 = Software (XON/XOFF) flow control (TTY link only)
             3 = Hardware AND software flow control

        If not specified, flow control defaults to NONE. Don't use
        Xon/Xoff with KISS!.

        CONFIG specifies special confifiguration for certain protocols.
        For KISS, it may optionally be used to specify a sequence of
        commands which switch a TNC into KISS mode at startup.

        RADIO secifies the number of the radio (if any) controlled by
        this interface. Required only if rig control is needed. 

        KISSOPTIONS are special options for the KISS protocol only:

             NONE     - Plain KISS (most TNC's use this) (default)

             POLLED   - For TNCs which send only when polled.

             CHECKSUM - Packets are 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, but their use of ACKMODE is optional.

</code> **SEE ALSO** <code>
        IFACES(6)      -- Interfaces.
        PORTS(6)       -- Ports.
        PROTOCOL(7)    -- Protocol Used on INTERFACE.
        XROUTER.CFG(8) -- Main Configuration File.

</code>
----
==== AXIP-IFACE ====
<code>AXIP-IFACE(6)           XROUTER REFERENCE MANUAL             26/9/2023

</code> **NAME** <code>
        AXIP-IFACE -- Interface Type "AXIP".

</code> **DESCRIPTION** <code>
        The AXIP interface is used, in conjunction with one or more
        PORTs, to provide AX25-over-IP links with other nodes.

        In this mode of operation, AX25 (plus CRC) is encapsulated
        within IP. This is less versatile that AXUDP, and only saves
        8 "internet" bytes per frame. See AXIP(9) for a more detailed
        explanation of AXIP.

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

        An AXIP interface is defined in 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 PORTs. You
        may define multiple interfaces if your ports need different
        MTU's.

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

        Each AXIP partner link requires its own PORT, in which the
        link parameters are defined. This is like operating an RF
        link on an exclusive frequency. The PORT is specified
        similar to this:

            PORT=8
                ID=AXIP link with WA3IP
                INTERFACENUM=7     <-- Points to the INTERFACE above
                IPLINK=55.73.88.69 <-- Partner's IP address/hostname
                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.

        To link with an AXIP partner on the SAME machine use a
        "localhost" address, e.g. "IPLINK=127.0.0.2".

        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 on a multi-tasking operating system means that
        RESPTIME should be more like 200ms

</code> **NOTES** <code>
        If no IPADDRESS is specified in XROUTER.CFG, AXIP is disabled.

        If there's either an EXTERN or a TUN interface, and IPLINK is
        not a "localhost" address, AXIP uses the XRouter stack, and
        will require correct IP routing to be set up in IPROUTE.SYS.

        If there's no EXTERN or TUN interface, or IPLINK is a
        localhost address, AXIP uses the Linux stack.

        In all cases XRouter will need the CAP_NET_RAW capability,
        unless it is run from a root account.

</code> **CAVEATS** <code>
        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. If you need more than one node, use AXUDP.

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

</code> **SEE ALSO** <code>
        AXIP(9)        -- About AXIP.
        IFACES(6)      -- Interfaces in XRouter.
        CAPFLAGS(6)    -- Capability Flags.
        PORTS(6)       -- Ports in XRouter.
        RUNROOT(6)     -- To Run as Root?
        XROUTER.CFG(8) -- Main Configuration File.

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

</code> **NAME** <code>
        AXTCP-IFACE -- Interface Type "AXTCP".

</code> **DESCRIPTION** <code>
        The AXTCP interface is used, in conjunction with a single
        PORT, to provide AX25-over-TCP links with other nodes.

        In this mode of operation, AX25 (plus CRC) is encapsulated
        within TCP streams (see AXTCP(9) for details). Unlike AXIP
        and AXUDP, AXTCP can work through NAT and firewalls, which is
        particularly useful for "mobile" nodes, which can't set up
        "port forwarding".

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

        AXTCP interfaces can act as server, client, or both at once,
        depending on which keywords are included. Servers require
        "port forwarding", clients do not.

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

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

        If the interface definition includes INTNUM, it will be a
        server. If it includes CONFIG it will be a client. If it
        includes both directives, it will be both server and client.

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

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


        Example AXTCP Client Interface
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
                INTERFACE=5
                        TYPE=AXTCP
                        MTU=256
                        CONFIG=KIDDER g8pzt.ath.cx 9393
                ENDINTERFACE

        The CONFIG directive activates client mode and specifies to 
        which server it will connect. The format is as follows:

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

             <alias> is the NetRom "alias" of the server
             <hostname>, <ipaddr> and <tcp_port> are those of the
              server

        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) appropriate 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 no two AXTCP interfaces may use the
        same INTNUM.

</code> **NOTES** <code>
        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.

        AXTCP always uses the Linux IP stack, so the port forwarding
        should be directed at the Linux IP address NOT XRouter's.

        If INTNUM is below 1024, XRouter will need to be granted the
        CAP_NET_BIND_SERVICE capability.

</code> **SEE ALSO** <code>
        AXTCP(9)       -- About AXTCP.
        IFACES(6)      -- Interfaces in XRouter.
        CAPFLAGS(6)    -- Capability Flags.
        PORTS(6)       -- Ports in XRouter.
        RUNROOT(6)     -- To Run as Root?
        XROUTER.CFG(8) -- Main Configuration File.

</code>
----
==== AXUDP-IFACE ====
<code>AXUDP-IFACE(6)          XROUTER REFERENCE MANUAL             26/9/2023

</code> **NAME** <code>
        AXUDP-IFACE -- Interface Type "AXUDP".

</code> **DESCRIPTION** <code>
        The AXUDP interface is used, in conjunction with one or more
        PORTs, to provide AX25-over-UDP links with other nodes.

        In this mode of operation, AX25 (plus CRC) is encapsulated
        within UDP/IP. This is more versatile that AXIP, and only
        costs an extra 8 bytes per frame. See AXUDP(9) for a more
        detailed explanation of AXUDP.

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

        An AXUDP interface is defined in 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 PORTs. You
        may define multiple interfaces if your ports need different
        MTU's.

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

        Each AXUDP partner link requires its own PORT, where the link
        parameters are defined. This is like operating an RF link on
        an exclusive frequency. The PORT is specified 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 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.

        UDPLOCAL and UDPREMOTE are the UDP "service port" numbers for
        each end of the link, and if omitted they default to 93. The
        numbers are independent, e.g. you may use 93 for UDPLOCAL and
        10093 for UDPREMOTE.

        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 on a multi-tasking operating system means that
        RESPTIME should be more like 200ms

</code> **NOTES** <code>
        The "rules" that determine which IP stack is used are a little
        complicated, and may be simplified in future:

        - If no IPADDRESS has been defined, AXUDP is totally blocked.

        - If the IPLINK is any LOCALHOST address, or no ETHERNET port
          is present, AXUDP uses the LINUX stack.

        - If an ETHERNET port is present, and IPLINK is NOT a
          LOCALHOST address, AXUDP uses XRouter's IP stack.

        - If XRouter's IP stack is used, IP routing must be set up
          correctly.

</code> **CAVEATS** <code>
        If the Linux IP stack is used, and UDPLOCAL is below 1024,
        XRouter will need CAP_NET_BIND_SERVICE capability, or will
        need to run from a "root" account.

</code> **SEE ALSO** <code>
        AXUDP(9)       -- About AXUDP.
        IFACES(6)      -- Interfaces in XRouter.
        CAPFLAGS(6)    -- Capability Flags.
        KISS(9)        -- KISS Protocol.
        PORTS(6)       -- Ports in XRouter.
        RUNROOT(6)     -- To Run as Root?
        XROUTER.CFG(8) -- Main Configuration File.

</code>
----
==== CAPFLAGS ====
<code>CAPFLAGS(6)            XROUTER REFERENCE MANUAL              23/9/2023

</code> **NAME** <code>
        CAPFLAGS -- Capability Flags

</code> **DESCRIPTION** <code>
        Starting with kernel 2.2, Linux divides the privileges
        traditionally associated with super-user into distinct units,
        known as "capabilities", which can be independently enabled
        and disabled.

        This allows non-privileged processes to be granted certain
        enhanced permissions without having to run the process as a
        privileged user.

        If XRouter is "run as root", i.e. it is started from a
        terminal which has "root" (super-user) privileges, it needs
        no further permissions.

        Otherwise, it will need CAP_NET_RAW capability in order to
        use TCP/IP via the LAN, WiFi or localhost. And it will need
        CAP_NET_BIND_SERVICE if you wish to open any "service ports"
        on the linux TCP/IP stack whose numbers are below 1024.

        Note: You do NOT need either of these capabilites for TCP/IP
        via serial ports, e.g. SLIP, KISS, AX25, PPP etc. You only
        need them for TCP/IP via LAN or WLAN.

        Program capabilities are changed using the Linux "setcap"
        command in a termnal window. Only a privileged user can
        confer privileges, so you must be root, or you must use
        "sudo".

        Once you have set XRouter's capability flags, you don't need
        to do it again unless you change the executable. 

</code> **EXAMPLES** <code>
        The following examples assume that the XRouter executable
        file is called "xrpi".

        Checking the capabilities:

             getcap xrpi

        Setting only the CAP_BET_BIND_SERVICE capability:

             sudo setcap cap_net_bind_service=pe xrpi

        Setting only the CAP_NET_RAW capability:

             sudo setcap cap_net_raw=pe xrpi

        Setting both capabilities:

             sudo setcap cap_net_raw,cap_net_bind_service=pe xrpi

</code> **CAVEATS** <code>
        Running XRouter with super-user privileges is easier and more
        convenient than running it as an unprivileged user. But
        technically it is more of a security risk. See RUNROOT(9) for
        more discussion about the pros and cons of running as root. 

</code> **SEE ALSO** <code>
        IP-STACKS(6) -- IP Stacks in XRouter.
        TCP-PORTS(6) -- TCP Server Ports.
        LAN(6)       -- LAN Interfacing.
        RUNROOT(6)   -- To Root or Not to Root?

</code>
----
==== COLOURS ====
<code>COLOURS(6)              XROUTER REFERENCE MANUAL            25/10/2023
</code> **NAME** <code>
        COLOURS -- Display Colours.

</code> **DESCRIPTION** <code>
        Most of the console background and text colours may be
        adjusted using the appropriate keywords in a CONSOLE
        configuration block in XROUTER.CFG.

        On DOS and Windows, XRouter can only display 16 colours.
        Although Linux allows more colours, the 16 colour limit
        still applies to XRPI and XRLin for the time being. This
        will be addressed in a future version.

        Colour names used within XROUTER.CFG are as follows:

        Dark:  BLACK, NAVY, GREEN, CYAN, RED, MAGENTA, ORANGE, SILVER

        Light: GREY, BLUE, LIME, TURQUOISE, PINK, CERISE, YELLOW,
               WHITE

        The names are misleading, being inherited from DOS XRouter
        where the display pallete was different. For example, on
        Windows, PINK is more like light red, and ORANGE is more of a
        brown colour, whilst RED is more like maroon.

        Some colour combinations display clearly, others are difficult
        to read.  For instance, WHITE text on BLACK background is
        clear, as is YELLOW on NAVY, but BLUE on BLACK, or PINK on
        LIME are hard to read.  The optimum background colour for most
        text colours (or vice versa) is BLACK.

        The background colour of the top status bar is fixed at
        SILVER, and the status windows all have RED title bars with
        WHITE text, and BLACK background for the main pane.  These
        colours were carefully planned and are not adjustable.

        The colours for the "consoles" are adjustable, but if you
        choose a SILVER background for a console's top line, it will
        blend with the top status bar above it and look untidy.

</code> **SEE ALSO** <code>
        CONSOLES(6)    -- About XRouter Consoles.
        XROUTER.CFG(8) -- Main Configuration File.

</code>
----
==== CONSOLES ====
<code>CONSOLES(6)             XROUTER REFERENCE MANUAL             26/9/2023

</code> **NAME** <code>
        CONSOLES -- About XRouter Conoles.

</code> **INTRODUCTION** <code>
        In this context "consoles" are one of the types of "window"
        in the XRouter display. They allow the sysop to interact with
        XRouter, for example to trace traffic, or make connections.

        Each console is fully independent, and you may have up to
        five of them. The first one is usually window number 8. Use
        the left and right "arrow" keys to navigate the windows.

</code> **CONSOLE LAYOUT** <code>
        The console display starts on the line below the grey XRouter
        status/menu bar. Each console has the following format:

        There is a single-line "status bar" at the top and a single
        line "menu bar" at the bottom. By default, these have a cyan
        background).

        Immediately above the menu bar is a single "command entry"
        line, with dark blue background and yellow text.

        The remaining central section is where monitored and received
        information is displayed, and this section is ANSI colour
        compatible.

        The console status bar shows the console number, the console
        callsign, and the connection state of that console. The
        bottom "menu bar" displays a context-sensitive menu for that
        console.

        The text and background colours of the various sections are
        fully configurable. The default settings were chosen to be
        ergonomic, but may not be to your taste, and can therefore
        be overridden by entries in the global section of
        XROUTER.CFG. The defaults can be further modified for
        individual consoles by adding console definition blocks.

        You may specify a different callsign for each console (used
        when making outgoing connections), or use the same callsign
        for each one.

        For details of how to configure the various console colours
        etc. see the console configuration page.

</code> **CONSOLE KEYS** <code>
        The following "special" keys are available when a console is
        displayed:

           <F1>                Display console help window.
           <F2>                Toggle monitoring on/off (MON).
           <F3>                Select port(s) to monitor. (MPORT)
           <F4>                Select monitored protocols. (MMASK)
           <F5>                Toggle disk capture on/off.
           <ESC>               Cancel operation / Disconnect.
           L/R arrow           Select previous / next console.
           U/D arrow           Scroll back/forward by one line.
           <PgUp>/<PgDn>       Scroll back/forward by one page.
           <End>               End scrollback.
           <Ctrl-LeftArrow>    Previous command in history.
           <Ctrl-rightArrow>   Next command in history.
           <Alt> / ALT-M       Open menu.
           <Alt-C>             Clear screen.
           <Alt-X>             Exit program.

        <F1> - Help

        Pressing <F1> pops up a dialog with the above information on
        it. The <ESC> key closes that dialog when you've finished
        with it.

        The contents of the help window are context-sensitive, i.e.
        they vary according to what you were doing when you pressed
        the <F1> key.

        <F2> - MON - Monitoring

        The <F2> key provides a quick way to toggle monitoring
        (protocol tracing) on and off, and is a shortcut for the
        MON ON|OFF commands.

        <F3> - MPORT - "Monitor port"

        The F3 key selects the port(s) to be monitored (traced), and
        is a shortcut for the MPORT command.

        Upon pressing this key you are invited to enter a number or
        string of numbers representing the combination of ports to
        monitor. If you press <F1> at this point a pop-up help
        window will show you the following information:

        To select port(s) to monitor, add together the following hex
        values:

            Port HEX    Port HEX     Port HEX     Port HEX
            ------------------------------------------------------
             0    1      8   100     16  10000    24   1000000
             1    2      9   200     17  20000    25   2000000
             2    4     10   400     18  40000    26   4000000
             3    8     11   800     19  80000    27   8000000
             4   10     12  1000     20 100000    28  10000000
             5   20     13  2000     21 200000    29  20000000
             6   40     14  4000     22 400000    30  40000000
             7   80     15  8000     23 800000    31  80000000

        e.g. #12 will monitor ports 4 and 1.

        Alternatively you may enter a single decimal port number,
        or a combination of ports separated by "+" e.g. "1+5+23".

        You may cancel the operation by pressing the <ESC> KEY.

        <F4> - Monitor Mask

        The <F4> key invites you to enter the "monitor mask" (aka
        trace mask), i.e. the protocols you wish to monitor.
        Pressing <F1> at this point pops up a help window with the
        following information:

             0001 - Incoming frames          0100 - ICMP
             0002 - Outgoing frames          0200 - TCP
             0004 - AX25 layer 2             0400 - KISS
             0008 - AX25 info frames         0800 - SLIP
             0010 - AX25 layer 3             1000 - PASSALL
             0020 - AX25 layer 4             2000 - Hex Dump
             0040 - IP frames
             0080 - ARP frames

        To select protocols, add together the desired hex flags from
        the above list. For example 0201 will show incoming TCP
        segments only, while 0241 will show the underlying IP
        datagrams as well. The default setting is 03FF, which shows
        all incoming and outgoing traffic from AX25 layer 2 upwards.

        The MMASK command has the same function.

        <F5> - Disk capture

        The <F5> key toggles disk capture on and off, and is a
        shortcut for the CAP[TURE] command.

        When capture is enabled, anything which is displayed in the
        central window of an XRouter console is also written to disk.
        This includes session activity and TRACE'd data. You can
        make it more specific using <F4> (MMASK) and <F3> (MPORT).

        Whereas the screen display is filtered to prevent it being
        garbled by binary data, the capture is pure binary, so it is
        useful for diagnostics.

        There is a seperate capture file for each XRouter "console",
        named CAPTUREnn.TXT where nn represents the console number
        (01 to 05). The capture files are created in the XRouter
        working directory. Although they have the extension ".TXT"
        to enable them to be easily opened with a text editor, they
        may somtimes contain characters which simple text editors
        can't display.

        Capture is fully independent on each console, and consoles
        may be captured concurrently. Switching between consoles, or
        scrolling consoles back, does not affect the capture.

        <ESC> - Cancel / Disconnect

        The <ESC> key "backtracks" if you have pressed <F1>, <F3> or
        <F4>. It can also be used to immediately disconnect a
        console session.

</code> **SELECTING CONSOLES** <code>
        The left and right "arrow" keys are used to scroll through
        the various XRouter windows. If you have enabled any
        consoles, they can be selected using this method.

        Note that when you reach the last window, it wraps back to
        the first and vice versa.

        Alternatively you may jump directly to a console by tapping
        Alt-V (view) followed by the console number, or you may
        select it from the window menu. The console numbers are
        shown on their top status bars.

</code> **WINDOW MENU** <code>
        On XRPi/XRLin, pressing <ALT> and <M> together temporarily
        replaces the console status bar with a grey "menu bar". On
        XRWin the <ALT> key by itself performs the same function.

        The menu bar currently has (F)ile (V)iew and (H)elp options,
        which can be navigated using the arrow keys, and actioned
        using the <RETURN> key.

        One character of each menu item is highlighted in red,
        indicating that it is a "hot key". Pressing the highlighted
        key causes that menu item to be actioned. For example ALT-M
        followed by "V" takes you into the (V)iew menu, from where
        pressing the "N" key takes you to the nodes monitor window.
        Or you can simply type ALT-V followed by "N".

        Upon actioning a menu item or pressing <ESC>, the menu is
        closed and the console top status bar returns.

</code> **FILE MENU** <code>
        The (F)ile menu item (shortcut ALT-F) only has 3 options at
        present.

        "(R)eload IProutes" re-reads the contents of IPROUTES.SYS,
        in case you made any changes during run-time.

        "(S)ave Nodes" saves the current nodes and routes tables to
        the XRNODES file.

        "e(X)it program" terminates XRouter.

</code> **VIEW MENU** <code>
        The (V)iew menu currently displays at least 8 options:

        "c(L)ear Window" clears the current console window.

        "S(Y)sop Chat" jumps to window number 1. This is "always on"
        chat between XRouter sysops, using XRChat channel 1234.

        "(C)hat Monitor" jumps to window 2. This gives an overview
        of the currently active channels on the XRChat and Round
        Table (BPQ) chat systems. It also shows who is on each
        channel, and the latest chat messages.

        "(S)ession Monitor" jumps to window 3, which shows who is
        currently connected and who has recently connected to your
        system. Additionally, it displays a log of the recent
        connections and disconnections. From here you can watch and
        delete sessions.

        "(N)odes Monitor" jumps to window 4, which shows how many
        NetRom nodes your system knows about, organised by hop count.
        It also shows which routes they were heard via, and the
        "health" of each node is indicated by colour and shape of
        the characters. From here you can browse the nodes table and
        mode stats.

        "(R)outes Monitor" jumps to window 5, which shows the status
        of the "Routes" to your NetRom neighbours. You can see at a
        glance which routes are healthy and which ones might need
        attention. 

        "(X)router Status" jumps to window 6, which gives an
        overview of the health of the system, and its activities.
        This is the window that displays when XRouter starts. 

        "Sec(U)rity Nonitor" jumps to window 7, which summarises
        some of the findings of XRouter's Intrusion Detection System
        (IDS). It is a work in progress. 

        Finally the consoles can be selected by entering a console
        number

</code> **HELP MENU** <code>
        "(A)bout XRouter" displays information about the program
        version and compilation date.

        "(H)elp Topics","(M)anual Topics and "(I)nfo Topics each
        open a window which lists the available topics, with one
        topic highlighted. The highlight can be moved using the
        arrow keys, and the topic can be viewed in a scrollable
        window by hitting RETURN on the highlighted topic.

        "(C)onfig Info" displays lots of informatuion about the
        XRouter configuration in a scrollable pop-up window.

</code> **COMMAND HISTORY** <code>
        Each console remembers the last 5 commands used on that
        console. These can be selected using the <Ctrl-LeftArrow>
        and <Ctrl-RightArrow> keys, and actioned by hitting <RETURN>

</code> **REVIEW MODE** <code>
        Scrollback or "review" mode enables you to look at something
        which went off the top of the screen. Unlike DOS XRouter,
        which displayed reviewed text in yellow, the Windows and
        Linux versions preserve the original colours during review.

        The up and down "arrow" keys control scrollback, along with
        the <PgUp>, <PgDn> and <End> keys. The only indication of
        review mode is the caption on the bottom menu bar.

        The console won't receive anything else while you are in
        review mode. However, if you are capturing to file, the
        capture is not interrupted by review mode.

        The default size of the review buffer is 400 lines of text,
        which is in addition to the current page. Thus if the
        console height is 50 lines, you can review the last 9 pages
        of activity. The size of the review buffer can be altered
        using the REVIEW directive, either (for all consoles) in the
        global section of XROUTER.CFG, or (for individual consoles)
        within a CONSOLE definition block.

</code> **LANGUAGES** <code>
        Most of the texts used on the XRouter display can be replaced
        with French, Spanish or Dutch texts. This is experimental,
        and the accuracy of the translations cannot be guaranteed,
        especially in the case of abbreviations. In some cases the
        English text is not translated.

        The console language is set using the CONSOLELANG directive
        in XROUTER.CFG. If you specify this globally, it is
        inherited by all consoles. If specified in a console
        definition block, it applies to that console only. If not
        specified, the console inherits DEFAULTLANG.

        No matter what CONSOLELANG is used, SESSIONS via the console
        use the language appropriate for CONSOLECALL, which in turn
        is specified by DEFAULTLANG, or by entries in LANGS.SYS.
        Finally the LANG command can be used to change the language
        for a session, but this doesn't affect the display itself.

</code> **CONFIGURATION** <code>
        The colours and other console parameters may be specified in
        XROUTER.CFG. If they are specified in the GLOBAL section,
        the values are inherited by all consoles. Alternatively they
        may be used in CONSOLE definition blocks to override the
        global defaults on a console-by-console basis.

        The following console definition keywords are available
        (defaults shown in brackets):

        ACTIONCOLOR     Text colour for XRouter actions (yellow)
        BOTWINBGCOLOR   Background for menu bar (cyan)
        BOTWINTXTCOLOR  Text colour for menu bar (white)
        CAPTIONCOLOR    Text colour for captions/headings
        CMDWINBGCOLOR   Background color for command line (navy)
        CMDWINTXTCOLOR  Text colour for command line (yellow)
        CONSOLECALL     Callsign for console operations (nodecall)
        ECHOCOLOR       Colour for text echoed from cmd line (yellow)
        MIDWINBGCOLOR   Background for central window (black)
        MIDWINTXTCOLOR  Text colour for central window (white)
        MMASK           Flags specifying protocols to trace (3f8)
        MPORTS          Ports to monitor by default (all)
        PROMPTCOLOR     Text colour for regular prompts (lightcyan)
        REVIEW          No. of lines of scrollback (400)
        RXCOLOR         Text color for RX tracing (lime)
        TOPWINBGCOLOR   Status line background colour (cyan)
        TOPWINTXTCOLOR  Status line text colour (white)
        TXCOLOR         Text colour for TX tracing (pink)
        WARNCOLOR       Text colour for warning/error messages

        Most of these should be self explanatory. However some of
        them may need clarification:

        CONSOLECALL
        This is the callsign used for making AX25 and NetRom
        connections from the console. You can set this independently
        of NODECALL or you may set them the same (which is the
        default if you omit the directive). You may set a different
        callsign on each console, and you may at any time override a
        console callsign using the "linked as" command.

        ECHOCOLOR
        When the sysop types some text into the command line and
        presses <enter>, the text is "echoed" into the main window
        using the ECHOCOLOR. This colour is chosen by default to be
        bright, and to be different from the other colours used in
        that window, to make it easy for the sysop to differentiate
        between sent and received text.

        MMASK
        This is the "monitor mask" (aka trace mask) which determines
        which protocols are traced by default. The mask is the sum
        of the desired hex values from the following list:

             0001 - Incoming frames          0100 - ICMP
             0002 - Outgoing frames          0200 - TCP
             0004 - AX25 layer 2             0400 - KISS
             0008 - AX25 info frames         0800 - SLIP
             0010 - AX25 layer 3             1000 - PASSALL
             0020 - AX25 layer 4             2000 - Hex Dump
             0040 - IP frames
             0080 - ARP frames

        E.g. 0201 shows incoming TCP segments only, while 0241 shows
        the underlying IP datagrams as well. The default setting is
        03FF, which shows all incoming and outgoing traffic from
        AX25 layer 2 upwards. The sysop may override this at any
        time using the MMASK command or the <F4> key.

        MPORTS
        This is the combination of PORTs which will be monitored
        (traced) by default, until changed by an MPORT command or
        the <F3> key. The default is to monitor ALL ports, but you
        may wish to limit this to the main ports of interest.

        The argument is either a HEX number between 0 and FFFFFFFF,
        a list of port numbers, or the words ALL or NONE. The hex
        value is calculated by adding together the desired values
        from this table:

            Port HEX    Port HEX     Port HEX     Port HEX
            ------------------------------------------------------
             0    1      8   100     16  10000    24   1000000
             1    2      9   200     17  20000    25   2000000
             2    4     10   400     18  40000    26   4000000
             3    8     11   800     19  80000    27   8000000
             4   10     12  1000     20 100000    28  10000000
             5   20     13  2000     21 200000    29  20000000
             6   40     14  4000     22 400000    30  40000000
             7   80     15  8000     23 800000    31  80000000

        However, it is usually more convenient to specify a list of
        port numbers. These may be supplied either as a series of
        single numbers, or in one or more ranges, or as combinations
        of the two. For example: MPORTS=1,3-5,8,10-12. There must be
        no spaces in the list.

        REVIEW
        This specifies the number of lines of scrollback available
        on the console. The value is a compromise, because setting a
        large value may increase the CPU usage and/or slow down the
        scrolling. The default is 400 lines, which is 8 pages on a
        50 line console. 

        NUMCONSOLES
        The total number of consoles defaults to 3. This may be
        changed using the NUMCONSOLES=n directive in the global
        section of XROUTER.CFG, where n is a number between 0 and 5.


        CONSOLE Definition Blocks

        Console definition blocks are used to specify any
        characteristics of consoles that differ from the default. If
        all the consoles are to be identical, you can simply define
        the characteristics in the GLOBAL section of XROUTER.CFG.
        Only those characteristics that differ from the defaults
        need to be specified.

        Console definition blocks start with CONSOLE=n where n is a
        number between 1 and 5, and end with ENDCONSOLE. They may
        contain any or all of the keywords listed above (except
        NUMCONSOLES). There should be one block for each console
        that differs from the default settings.

        For example:

            CONSOLE=3
                MIDWINBGCOLOR=NAVY
                MIDWINTXTCOLOR=WHITE
                CMDWINBGCOLOR=GREEN
                CONSOLECALL=G8PZT-4
                MMASK=1f        ; AX25/Netrom only
                MPORTS=1-2      ; Monitor ports 1 and 2 only
            ENDCONSOLE
	  

</code> **SEE ALSO** <code>
        COLOURS(6)     -- XRouter Display Colours.
        CONSOLELANG(7) -- Console language
        DEFAULTLANG(7) -- Specify default language
        LANGS.SYS(8)   -- Language selection file
        XROUTER.CFG(8) -- Main Configuration File.

</code>
----
==== EXTERN-IFACE ====
<code>EXTERN-IFACE(6)         XROUTER REFERENCE MANUAL             26/9/2023

</code> **NAME** <code>
        EXTERN-IFACE -- Interface Type "EXTERNAL". .

</code> **DESCRIPTION** <code>
        The EXTERNAL interface type is intended for interfacing with
        Ethernet, WiFi and other things yet to be decided.

        The name is a hang-over from XR16 (DOS), where an external
        TSR program managed the interface with the NIC packet driver.
        The external interface was also used to interface with BPQ-
        compatible drivers. XR32 (Windows) also used an external
        program, "NdisXpkt", to provide the Ethernet connection.

        XRPi / XRLin don't need an external driver for Ethernet, but
        rather than confuse existing XR sysops by introducing a new
        interface type, the same configuration was used.

        A typical Ethernet INTERFACE and PORT combination is shown
        below:

            INTERFACE=5
                ID=eth0
                TYPE=EXTERNAL
                PROTOCOL=ETHER
                MTU=1064
            ENDINTERFACE

            PORT=7
                ID=Ethernet Adaptor
                INTERFACENUM=5
                IPADDRESS=192.168.0.221
            ENDPORT

        The interface and port numbers are for example only.

        In the INTERFACE block, the ID directive specifies the device
        name, e.g. "eth0" for the first Ethernet adaptor or "wlan0"
        for wireless LAN adaptor. These names may vary from platform
        to platform, e.g. on MX-Linux the wireless lan adaptor might
        be named "eth1" not "wlan0".

        The PROTOCOL directive specifies the hardware layer protocol
        for the interface. At present only ETHER (Ethernet) protocol
        is used on this type of interface.

        In the PORT block, The ID directive specifies a human-readable
        brief description of the interface, e.g. "LAN Adaptor
        (192.168.0.221)".

        The IPADDRESS directive specifies the IP address to be used on
        this interface. This overrides XRouter's "core" IPADDRESS for
        this port only. It must be different to the Linux IP address,
        and must be appropriate for the local subnet.

</code> **CAVEATS** <code>
        If XRouter is run from an account with root priviliges, no
        special conditions apply, otherwise its access to resources
        is restricted by Linux's security policies.

        To use the EXTERNAL interface without root priviliges, the
        XRouter executable needs to be granted CAP_NET_RAW capability.
        See CAPFLAGS for more information.

</code> **SEE ALSO** <code>
        IFACES(6)      -- Interfaces.
        CAPFLAGS(6)    -- Capability Flags.
        PORTS(6)       -- Ports in XRouter.
        RUNROOT(6)     -- Run as Root or Not?
        XROUTER.CFG(8) -- Main Configuration File.

</code>
----
==== IFACES ====
<code>IFACES(6)              XROUTER REFERENCE MANUAL              23/9/2023

</code> **NAME** <code>
        IFACES -- Interfaces in XRouter.

</code> **DESCRIPTION** <code>
        An XRouter INTERFACE is a physical (e.g. a COM port) or
        virtual point of connection between XRouter and somewhere
        else. The "somewhere else" is usually the world outside the
        PC, but it may also be an internal connection to other
        applications on the same PC.

        This is not to be confused with Linux interfaces, which exist
        at a lower level, within the Linux kernal.

        Apart from the keyboard input, the screen output, and the
        internal connection with Linux's TCP/IP services, everything
        that enters or leaves XRouter must ultimately pass through an
        INTERFACE.

        Some types of interface support only a single "channel" of
        data, whilst others can support multiple channels, either
        due to their physical construction, or the protocol used.

        Interfaces usually have one or more PORTS "attached" to them.
        A PORT is the point of interaction between the various
        protocol modules and *one channel* of an interface.

        However some interfaces, such as those used by XRouter to
        emulate other types of hardware or software, do not support
        ports. An example of this latter type would be the TNC2
        interface.

        Defining Interfaces in XRouter
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        XRouter interfaces are configured using INTERFACE definition
        blocks within XROUTER.CFG.

        The interface definition block must reside in the GLOBAL
        section of XROUTER.CFG, i.e. you cannot define an interface
        within any other block.

        The block starts with the directive "INTERFACE=n", where n is
        a unique number used to identify the interface. The actual
        number is unimportant, as long as it is greater than zero and
        no other interface uses the same number. The block ends with
        ENDINTERFACE.

        The block must contain at least the TYPE and MTU directives,
        otherwise XRouter will refuse to start. Additional directives
        may be required, depending on the TYPE. The full range of
        interface keywords is summarised in OPTIONS below

</code> **OPTIONS** <code>
        Interface Keywords - Overview: (*=mandatory)
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        APPLNUM         Application number (DEDHOST only)
        CHANNEL         Channel on multi-channel hardware
        CHANNELS        No. of TNC channels (DEDHOST only)
        COM             Usually the hardware device name
        CONFIG          Hardware-specfic config options
        ENDINTERFACE  * Ends interface definition block
        ETHADDR         Ethernet address (NdisXpkt only)
        FLOW            Flow control options (async only)
        ID              Interface identification string
        INTNUM          Was interrupt number, now multi-purpose
        IOADDR          Was I/O address, now multi-purpose
        KISSOPTIONS     Options for KISS interfaces only
        MTU           * Maximum Transmission Unit
        PROTOCOL        Protocol used on this interface
        RADIO           Radio controlled by this interface
        SPEED           Serial (async) or RF (SCC) baud rate
        TYPE          * Type of hardware

        Interface Keywords - Detail
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~

        APPLNUM
          Application number (WA8DED hostmode interfaces only).
          Specifies which application will be using this interface.
          Must match the number in the corresponding APPL block.
 
        CHANNEL
          Channel on multi-channel hardware (e.g. SCC cards). XRouter
          does not currently support SCC cards on Linux, so this
          keyword should not be used.
 
        CHANNELS
          For WA8DED hostmode interfaces only. Specifies the max no.
          of host channels (between 1 and 32) the interface will
          provide.
 
        COM
          This is mandatory for some interfaces only. For ASYNC and
          YAM types, it specifies the name of the serial
          communication device, e.g. "/dev/ttyUSB0". For the TUN
          interface it specifies an optional tunnel name, for example
          "tun99". For a UDP interface it specifies the remote end's
          UDP port. Setting COM=0 can be used to "park" an interface.
 
        CONFIG
          Hardware-specific config options. The format depends on the
          interface type.  Can be used to switch real TNC into KISS
          mode at startup for example.
 
        ENDINTERFACE (mandatory)
          Marks the end of the INTERFACE definition block. Subsequent
          keywords will be treated as GLOBAL. 

        ETHADDR
          (Not currently used in XRouter and might be removed)
          Ethernet address in form xx:xx:xx:xx:xx:xx. Was used in
          XR32 only for EXTERNAL drivers using ETHER protocol, such
          as the NdisXpkt driver. 

        FLOW
          Flow control options (ASYNC interfaces only):

            0 = No flow control
            1 = Hardware (RTS/CTS) flow control
            2 = Software (XON/XOFF) flow control (TTY link only)
            3 = Hardware AND software flow control

          If not specified, flow control defaults to NONE. Don't use
          Xon/Xoff with KISS. 

        ID
          Interface Identification. This is a plain text string which
          identifies the interface on various displays. Keep it
          concise, e.g "Ethernet". 20 characters max.
 
        INTNUM
          Used by AGW, AXTCP, TCP, and UDP interfaces. For the AXTCP
          and TCP servers, this specifies the TCP port the server
          should listen on. For UDP interfaces it specifies the local
          UDP port. For the AGW interface it specifies the TCP port
          used to connect with the AGW Packet Engine.

          (This is a recycled keyword, which was used in XR16 to
          specify a hardware interrupt number). 

        IOADDR
          For AGW interfaces, this specifies the IP address of the
          AGW packet Engine (or Direwolf etc). If not specified, it
          defaults to 127.0.0.1 (localhost). Not currently used
          anywhere else.

          (This is another recycled keyword, which was used in XR16
          to specify an hardware IO address.) 

        KISSOPTIONS
          Options for KISS interfaces only:

            NONE     - Plain KISS (most TNC's use this) (default)

            POLLED   - For TNCs which send only when polled.

            CHECKSUM - Packets are 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.

            NOPARMS  - Don't send TNC configuration parameters.

          POLLED and SLAVE are mutually exclusive. BPQKISS eproms
          require POLLED and CHECKSUM, but their use of ACKMODE is
          optional.
 
        MTU (mandatory)
          Maximum Transmission Unit. This specifies the maximum size
          for the data portion of a packet transmitted on the
          interface.

          IP datagrams are sized or fragmented according to the MTU
          of the interface on which they are transmitted.

          XRouter allows MTU's up to 1500 bytes, but setting MTU
          above 256 is not recommended on AX25 ports, because the
          buffer size on TNC-based nodes is usually only big enough
          for a 256-byte data field.

          This is a mandatory keyword, although for some interface
          types the value has no meaning and is ignored. If in doubt,
          use 256.
 
        PROTOCOL
          Protocol to use on the interface:

            ASCII    - Remote consoles (TTY) via ASYNC ports
            AX25     - Pure ax25, no CRC or HDLC
            AXIP     - AX25 over IP (with CRC)
            AXTCP    - AX25 over TCP/IP (with CRC)
            AXUDP    - AX25 over UDP/IP (with CRC)
            DEDHOST  - DEDHOST emulation
            ETHER    - Ethernet
            HDLC     - For use with YAM modem, and some EXTERNAL
                       drivers.
            IP       - Internet Protocol, may be used on TCP,
                       UDP,  TUN and LOOPBACK interfaces.
            KISS     - For driving KISS TNCs or wired links.
            MODEM    - Hayes compatible PSTN modem.
            NETROM   - Netrom backend serial link.
            NONE     - Use this with type=loopback
            PPP      - Point to Point Protocol
            SLIP     - Serial Line Internet Protocol 
            TNC      - External TNC/device in normal cmd mode
            TNC2     - TNC2 emulation.

            (see PROTOCOL(7) for more detail)

        RADIO
          Number of the radio (if any) controlled by this interface.
          Required only if rig control is needed.

        SPEED
          The serial port baud rate for ASYNC interfaces only. Don't
          include a comma.
 
        TYPE (mandatory)
          Interface type as follows:

            AGW            AGW Packet Engine
            ASYNC          Serial (e.g. RS232)
            AXIP           AX25 over IP
            AXTCP          AX25 over TCP
            AXUDP          AX25 over UDP
            EXTERNAL       External driver
            LOOPBACK       Internal loopback
            TCP            TCP pseudo-interface
            TUN            Linux "tunnel" (tun) interface
            UDP            UDP pseudo-interface
            YAM            YAM 1200/2400/9600 modem


</code> **EXAMPLES** <code>
        KISS TNC on USB to RS232:
        ~~~~~~~~~~~~~~~~~~~~~~~~~

          INTERFACE=1
              TYPE=ASYNC
              COM=/dev/ttyUSB1
              SPEED=9600
              PROTOCOL=KISS
              KISSOPTIONS=POLLED,CHECKSUM,ACKMODE
              MTU=256
          ENDINTERFACE

        Ethernet:
        ~~~~~~~~

          INTERFACE=2
              TYPE=EXTERNAL
              ID=/dev/eth0
              PROTOCOL=ETHER
              MTU=1064
          ENDINTERFACE

        AXUDP Interface:
        ~~~~~~~~~~~~~~~

          INTERFACE=9
              TYPE=AXUDP
              MTU=256
          ENDINTERFACE

</code> **SEE ALSO** <code>
        AGW-IFACE(6)    -- AGW Interface.
        ASYNC-IFACE(6)  -- ASYNC (serial) Interface.
        AXIP-IFACE(6)   -- AX25 over IP Interface.
        AXTCP-IFACE(6)  -- AX25 over TCP Interface.
        AXUDP-IFACE(6)  -- AX25 over UDP Interface.
        EXTERN-IFACE(6) -- External / Ethernet Interface
        LOOP-IFACE(6)   -- Loopback Interface.
        PORTS(6)        -- PORTS in XRouter.
        PROTOCOL(7)     -- Protocol Used on INTERFACE.
        TCP-IFACE(6)    -- TCP Interface.
        TUN-IFACE(6)    -- Tunnel Interface.
        UDP-IFACE(6)    -- UDP interface.
        XROUTER.CFG(8)  -- Main Configuration File

</code>
----
==== IP-STACKS ====
<code>IP-STACKS(6)          XROUTER REFERENCE MANUAL               22/9/2023

</code> **NAME** <code>
        IP-STACKS -- TCP/IP Stacks in XRouter.

</code> **DESCRIPTION** <code>
        A TCP/IP "stack" is a set of protocols layered on top of
        each other in such a way that each layer only talks to the
        layer immediately above or below it. There is no lateral
        communication within layers.

        At the top of the stack is the "Application Layer", which is
        basically where humans and processes interact with the stack,
        and at the bottom is the "Physical Layer", which is where the
        PC interfaces to the outside world, via Network Interface
        Cards (NIC's), sound cards, COM ports etc.

        The following diagram is a greatly simplified version of
        XRouter's TCP/IP stack. Some components have been omitted for
        clarity, and to save space. 

          .----------------------------------------------------.
          |                 (Application Layer)                |        
          | TELNET | FTP | HTTP | etc.. | DNS | RIP | PING etc.|
          |--------'-----'------'-------'-----------'----------|
          |             TCP             |    UDP    |   ICMP   |
          |-----------------------------'-----------'----------|
          |                      IP                            |
          |--------------------------------------.------.------|
          |               ARP                    |      |      |
          |------------.-------------------------|      |      |
          |  Ethernet  |       Ax25              | SLIP | PPP  |
          |------------|------------------.------|      |      |
          |  NDISXPKT  |      AGWPE       | KISS |      |      |
          |------------|-----------.------'------'------'------'
          |     NIC    | SOUNDCARD |        COM PORTS          |
          |                  (Physical Layer)                  |
          '----------------------------------------------------'

                    Fig.1 - XRouter's TCP/IP Stack

        To illustrate the workings of a TCP/IP stack, imagine that the
        application initiates a TELNET connection. It can be seen from
        Fig.1 that in order to reach the outside world, TELNET uses
        TCP, which in turn uses IP. From that point downwards there
        are several choices, depending on the destination address, the
        IP routing tables, and the hardware interfaces that have been
        defined in XROUTER.CFG.

        If the destination is an Internet site, the data may pass down
        through ARP, Ethernet and NDIS, to emerge from the NIC onto
        the LAN, thence to the Internet router and the Internet.

        If however the destination was a local Ham Radio TCP/IP hub,
        the data might pass from IP down through ARP and AX25, then it
        would either go via KISS and a COM port to a TNC, or via AGW
        Packet Engine and a sound card, thence to the radio.

        Alternatively the destination may be another PC, linked via
        COM ports. In this case, the data would pass from IP down
        through SLIP or PPP to the COM port.

        Two Stacks
        ==========
     
        Although XRouter has its own TCP/IP stack, Linux has a much
        larger and more comprehensive stack of its own. The two are
        independent of each other, and different to each other...

        History Digression:
        ~~~~~~~~~~~~~~~~~~~
        
        XRouter's stack originated in the 1990's, when XRouter ran on
        DOS. There was no TCP/IP stack in DOS, so XRouter evolved as a
        way to provide one, both for Internet and for TCP/IP over RF.

        Because of this, XRouter's stack was multi-homed. i.e. it
        could exist on several networks at the same time, with
        different IP addresses on each network. For example it may be
        simultaneously using the IP address 44.131.91.2 for radio
        links, 192.168.0.23 for Ethernet, and 10.0.0.2 on a SLIP link.

        Many years later, when XRouter was ported to Windows and
        became "XR32", Windows by now had a comprehensive TCP/IP stack
        of its own. Consequently, some of the functionality provided
        by XR32's stack could be provided equally well by the Windows
        stack.

        But not all of it. Windows could not provide any AX25
        services, and it was almost impossible to set up and use
        Windows TCP/IP via packet radio RF links.

        So XR32 was able to make use of Windows' TCP/IP stack for
        Internet operations, whilst using its own stack for TCP/IP
        over radio. Or it could be configured to ignore Windows'
        stack and do everything via its own stack. Or a mixture of
        the two, as specified by the sysop.

        XR32 was later ported to Linux to become XRPi/XRLin. But
        Linux already has a very powerful networking stack which
        includes AX25, so some might question the need for XRouter to
        have a stack, or even to exist at all!

                    ----------------------------

        The point is, XRouter is an experiment in amateur networking.
        New ideas can be quickly tried out without breaking the Linux
        stack, or going through a long-winded process to get the code
        incorporated into the Linux kernal. Ideas that don't succeed
        can easily be discarded, and no kernals are harmed in the
        attempt.

        XRouter can do many things that the Linux stack cannot, all
        in one simple package. The sysop has full control over which
        TCP/IP services use which stack.

        At the application layer, XRouter can use either or both
        TCP/IP stacks, as shown in the simplified diagrams below:


                .-----------------------------------------.
                |         XRouter Application Layer       |
                |-----------------------------------------|
                |  XRouter IP Stack  |  Linux IP stack    |
                |    192.168.0.23    |    192.168.0.1     |
                '-----------------------------------------'

                      Fig.2 - XRouter Using Both Stacks

        Figure 2 shows the application layer sitting astride both
        stacks. For example, the FTP server might be available on
        both kernal and XRouter IP addresses, either with the same or
        different TCP port numbers.

        Or you might wish to restrict the FTP server to the Linux
        stack, firewalled from the outside world, whilst the Telnet
        server sits on the XRouter stack, port-forwarded from the
        outside world. The possibilities are endless, and up to you.


                .--------------------.
                | XRouter Appl Layer |
                |--------------------|--------------------.
                |  XRouter IP Stack  |  Linux IP stack    |
                |    192.168.0.23    |    192.168.0.1     |
                '-----------------------------------------'

                       Fig.3 - XRouter Using Own Stack

        Figure 3 shows XRouter's application layer sitting wholly
        astride its own TCP/IP stack, such that it makes no use of
        the Linux stack at all.


                                     .--------------------.
                                     | XRouter Appl Layer |
                .--------------------|--------------------.
                |  XRouter IP Stack  |  Linux IP stack    |
                |    192.168.0.23    |    192.168.0.1     |
                '-----------------------------------------'

                       Fig.4 - XRouter Using Linux Stack

        Conversely all of XRouter's applications (FTP, HTTP, Telnet
        etc.) could use only the Linux stack, as shown in figure 4.
        In this case it wouldn't even be necessary to give XRouter
        an IP address.

        At the physical layer, XRouter's TCP/IP stack shares the
        Ethernet and WiFi adaptors with Linux, whilst using its own
        IP addresses. This is shown in the simplified diagram below
        (which omits KISS etc. for clarity):


                .-----------------------------------------.
                |  XRouter IP Stack  |  Linux IP stack    |
                |    192.168.0.23    |    192.168.0.1     |
                |-----------------------------------------|
                |          Ethernet / WiFi Adaptors       |
                '-----------------------------------------'

                Fig.5 - IP Stacks Sharing Physical Resources


        To Root or Not to Root?
        ~~~~~~~~~~~~~~~~~~~~~~~

        In order to directly share the physical resources, XRouter
        either needs root privileges, or it needs to be given
        permission to access raw network resources.

        Running as root is more convenient in that it allows XRouter
        to open any TCP or UDP port on the Linux stack, but some may
        consider it to be a security risk.

        For example, in the highly unlikely event that someone breaks
        out of XRouter to a command line, they could have access to
        the whole machine. However, XRouter has been in use for
        several years fully open to the Internet, without incident.

        Running XRouter as a non-root user is safer. Even if a
        miscreant managed to break out to a command shell, he would
        only have access to that user's directory tree.

        The downside of non-root is that Linux would not allow
        XRouter to open TCP/UDP port numbers below 1024 on the Linux
        stack. So for example you could not run FTP servers at port
        21 on both stacks. There would be no restriction on the
        XRouter stack, but the port number on the Linux stack would
        have to be greater than 1023.

        But that is a small price to pay for the added security.

        If you run XRouter as shown in figure 4, it needs no special
        privileges at all. But you will not be able to trace much of
        the TCP/IP traffic, and some facilities will be unavaliable.

        Which Stack to Use?
        ~~~~~~~~~~~~~~~~~~~

        The choice of how your TCP/IP packets are routed, and which
        stack your services appear on, is entirely under your
        control. It could have been automated, but that would have
        deprived you of choice.

        If you haven't defined an Ethernet or Wlan port, and you
        haven't defined any RF, SLIP or PPP routing, TCP/IP traffic
        will use the Linux stack. If you are not running XRouter from
        a root account, and have not set the correct capability flags
        on the program, some services such as PING AXIP, IPIP and
        TELNET won't be available, and your server ports may be
        restricted to service numbers 1024 and above.

        If you have defined an Ethernet or Wlan port, all TCP/IP
        traffic (except to localhost) will try to route via XRouter's
        own stack, and all servers are on that stack unless the
        defaults are overidden.

        The way to force traffic via the Linux stack is to use
        IP ROUTE entries with mode "k" (kernal) instead of "d".
        Anything not caught by a "k" entry will then be routed via
        XRouter's stack. 
	  
</code> **SEE ALSO** <code>
        IP(1)          -- IP Configuration Commands.
        IPROUTE.SYS(8) -- IP Configuration & Routing File.
        IP-PRIMER(9)   -- IP Primer.

</code>
----
==== LAN ====
<code>LAN(6)                 XROUTER REFERENCE MANUAL              23/9/2023

</code> **NAME** <code>
    LAN -- LAN Interfacing. 

</code> **DESCRIPTION** <code>
        There are TWO ways for XRouter to interface with the LAN or
        WiFi. Which one you choose depends on the facilities you need.

        The "basic" method accesses the LAN via the Linux kernal.

        This mode supports servers, AXIP, AXUDP, AXTCP, IPIP, IPUDP,
        Telnet, PING, TraceRoute etc.

        It does NOT support direct IP routing between XRouter ports
        and the LAN.

        For example, it wouldn't be able to route "raw" IP from a PPP
        port or RF network onto the LAN (and vice versa).

        But it CAN route encapsulated traffic to and from the LAN.
        For example, you could receive IP over the radio, or over
        AXIP / AXUDP / IPIP / IPUDP / PPP / SLIP etc, and route it
        out via the LAN to another node, providing it is encapsulated
        in IPIP, IPENCAP, IPUDP, IP-over-AXUDP, IP-over-AXIP,
        IP-over-AXTCP etc.

        Using basic mode, it is not possible (yet) to "trace" the
        Linux kernal TCP/IP activity. Only encapsulated traffic and
        non-LAN traffic can be traced.

        Basic mode does not need an INTERFACE or PORT for the LAN.
        All it needs is a "type k" (kernal) default route in
        IPROUTE.SYS like this:

            ip route default  0  *  k

        In this mode, all servers and LAN traffic in and out of
        XRouter use Linux's LAN IP address.

        The "regular" method for accessing the LAN bypasses the Linux
        kernal, talking to the hardware in a more direct way.

        This mode gives XRouter its own LAN address and IP stack,
        independent of the Linux one.

        It supports all the above modes, PLUS it supports direct IP
        routing between XRouter ports and the LAN. All LAN traffic
        to and from XRouter can be "traced".

        Regular mode uses an EXTERNAL interface, to which a PORT is
        attached. They are declared as follows:

            INTERFACE=3
                TYPE=EXTERNAL        ; External device driver
                ID=eth0              ; Device to use
                PROTOCOL=ETHER       ; Protocol
                MTU=1064             ; Largest packet size
            ENDINTERFACE

        The "ID=" directive tells XRouter which Ethernet adaptor to
        use. This is normally "eth0". If you use an invalid device
        name, e.g. "eth1", XRouter will start, but will not be able
        to use Ethernet.

        Device "eth0" is usally the Ethernet adaptor and wlan0 is
        usually the WiFi adaptor. However, the WiFi may appear as
        "eth1".

        The only PROTOCOL accepted at present is ETHER.

        The corresponding Ethernet PORT is declared like this:

            PORT=1                     ; Port number
                ID=Ethernet            ; Description
                INTERFACENUM=3         ; Interface to use
                IPADDRESS=192.168.0.2  ; Ethernet IP address
                NETMASK=255.255.255.0  ; Network mask
                etc...

        INTERFACENUM must refer to the number of the INTERFACE
        previously defined.

        The port number is not important. It is merely a "handle" for
        users of the port. It doesn't have to match the INTERFACE
        number.

        IPADDRESS specifies XRouter's IP address, overriding the
        global IP address only on that port.

        Make sure you choose a different IP address to any that Linux
        is using!

        You will also need to set up some LAN IP routing in
        IPROUTE.SYS, for example:

            # Default route via gateway 192.168.0.100 on port 1:
            ip route default  1  192.168.0.100  d
            #
            # Local subnet is routed direct on port 1:
            ip route add 192.168.0.0/24          *  1  d

</code> **CAVEATS** <code>
        If XRouter is run as a root user, no special conditions apply.

        If not run as root, its access to resources is restricted by
        Linux's security policies.

        When running as a non-root user, "basic" mode requires
        XRouter to have CAP_NET_BIND_SERVICE capability if any of its
        server ports on the Linux stack are below 1024. See
        TCP-PORTS(6) for more information and workarounds.

        To run "normal mode" as a non-root user, the "XRouter"
        executable needs CAP_NET_RAW capability. See CAPFLAGS(6) for
        more information. 

</code> **SEE ALSO** <code>
        IP-STACKS(6)   -- IP Stacks in XRouter.
        TCP-PORTS(6)   -- TCP Server Ports.
        IPROUTE.SYS(8) -- IP Routing Tables.
        CAPFLAGS(6)    -- Capability Flags.
        XROUTER.CFG(8) -- Main Configuration File.

</code>
----
==== LOOP-IFACE ====
<code>LOOP-IFACE(6)           XROUTER REFERENCE MANUAL             26/9/2023

</code> **NAME** <code>
        LOOP-IFACE -- Interface type "LOOPBACK".

</code> **DESCRIPTION** <code>
        The LOOPBACK interface is often misunderstood and mis-used.

        It is a relic of the DOS era, and has no practical use other
        than for test and development. YOU SHOULD NOT USE IT.

        It is an internal loopback within XRouter's stack only. It
        does NOT connect to Linux, and should be disabled if not
        needed because at the very least it may cause confusion, and
        may cause unwanted side effects.

        The "dummy" XROUTER.CFG file uses this interface for
        initial "off-line" testing, because it is the easiest way
        to create an INTERFACE and PORT, which XRouter needs
        before it will start. It gets a new sysop up and running
        quickly, and can always be used as a "known good"
        configuration, either from which to build a system, or to
        return to when troubleshooting.

        Once you have added some "real" interfaces and ports, you
        should remove or comment out the loopback one.

        The interface requires TYPE=LOOPBACK, PROTOCOL and MTU
        directives. Accepted PROTOCOLs are as follows:

            AX25     - Plain AX25, no CRC
            ETHER    - Ethernet
            HDLC     - AX25 with CRC, but no HDLC flags
            IP       - Plain IP
            KISS     - Basically AX25 within SLIP
            NETROM   - Netrom backend serial link.
            PPP      - Point to Point Protocol
            SLIP     - Serial Line Internet Protocol

            (see PROTOCOL(7) for more detail)

</code> **EXAMPLE** <code>
        #  Example "loopback" interface, allowing self-connects for
        #  test purposes only. This type of interface supports one
        #  PORT only.
        #
        INTERFACE=3
            TYPE=LOOPBACK
            PROTOCOL=KISS
            MTU=576
        ENDINTERFACE
        #
        #  Example loopback port, attached to loopback interface
        #  Use with caution. May cause catastrophic endless loops
        #  if IP routing is configured incorrectly.
        #
        PORT=3
            ID=Internal Loopback
            INTERFACENUM=3
        ENDPORT
        #

</code> **SEE ALSO** <code>
        IFACES(6)      -- Interfaces.
        KISS(9)        -- KISS Protocol.
        PORTS(6)       -- Ports in XRouter.
        PPP(9)         -- Point to Point Protocol.
        PROTOCOL(7)    -- Protocol Used on INTERFACE.
        XROUTER.CFG(8) -- Main Configuration File.

</code>
----
==== PORTS ====
<code>PORTS(6)               XROUTER REFERENCE MANUAL              26/9/2023

</code> **NAME** <code>
        PORTS -- PORTS in XRouter.

</code> **DESCRIPTION** <code>
        A PORT is a point of interaction between XRouter's central
        "core" and the INTERFACES which connect to the world outside
        XRouter. You cannot have a PORT without having an INTERFACE
        to attach it to.

        All AX25 operations are PORT-based, where a PORT usually
        corresponds to a single radio frequency. Ports allow XRouter
        to direct output to a specific device, and receive input
        from that device.

        Each port is "attached" to a CHANNEL on an INTERFACE. Some
        interfaces are single-channel, and can therefore support only
        one PORT. Others are multi-channel, and can have several
        ports attached to them.

        For example, an ASYNC interface connected to a PSTN modem
        supports only one channel of communication with the modem,
        therefore it can only support one port. But an ASYNC
        interface using KISS protocol can support a multi-channel
        TNC, whereby each channel is connected to a seperate radio on
        its own frequency, thus there would be one PORT for each
        channel.

        For historical reasons, XRouter will not run unless there is
        at least one PORT.

        Defining Ports in XRouter:
        ~~~~~~~~~~~~~~~~~~~~~~~~~~

        XRouter ports are configured using PORT definition blocks
        within the GLOBAL section of XROUTER.CFG. The blocks start
        with the keyword PORT and end with ENDPORT.

        They contain "directives" of general form <keyword>=<value>,
        each on a separate line. (If you do not understand the
        significance of the <>, please see the conventions section).
        Keywords are not case sensitive, and may be specified in any
        order.

        For example:

            PORT=2
                (directives here)
            ENDPORT

        Some directives are mandatory, but most are optional. The
        full range of port keywords is summarised below: 

</code> **OPTIONS** <code>

        PORT Keywords - Overview (*=mandatory)
        ~~~~~~~~~~~~~~~~~~~~~~~~

        APPLMASK        Controls which applications are visible
        APRSPATH        Default digipeater path for APRS
        BCAST           List of destinations for "broadcasting"
        BCFROM          Callsigns who may broadcast
        CFLAGS          Controls AX25 up/downlinking
        CHANNEL         Channel to use on interface (A)
        CHATALIAS       Port override for global chatalias
        CHATCALL        Port override for global chatcall
        CTEXT           Text to send to incoming connectees
        CTFLAGS         Controls who gets the CTEXT
        CWID            Text to send in CW every 30' (SCC only)
        DHCP            Enables / disables DHCP client (0)
        DIGIFLAG        Controls digipeating (7)
        DIGIPORT        Port to digipeat on (this port)
        DYNDNS          Enable / disable Dynamic DNS update client
        ENDPORT       * Ends port definition block
        EXCLUDE         List of callsigns not allowed to connect
        FEC             Enable / disable Forward Error Correction (0)
        FRACK           AX25 Frame Acknowledgement time ms (7000)
        FREQUENCY       Radio frequency in Hz (0).
        FULLDUP         Allow simultaneous TX/RX (SCC only)
        ID            * Text to identify port on ports display
        IDPATH          Dest & digi path for ID beacons ("ID")
        IDTEXT          Port override for global IDTEXT
        INITSTR         Modem initialisation string (modem only)
        INTERFACENUM  * Interface number this port is bound to
        INTERLOCK       Prevents simultaneous TX on SCC cards
        IPADDRESS       Port override for global IP address
        IPLINK          IP address / hostname of AXIP/AXUDP peer
        MAXFRAME        Max outstanding AX25 L2 frames (3)
        MAXHOPS         Port override for global MAXHOPS
        MAXTT           Port override for global MAXTT
        MHEARD          Enable / disable MHeard on this port
        MHFLAGS         Controls contents of MHeard list (255)
        MINQUAL         Port override for global MINQUAL
        MINTXQUAL       Min NetRom quality to broadcast
        NETMASK         Subnet mask used with IPADDRESS
        NODESINTERVAL   Port override for global NODESINTERVAL
        PACLEN          Port override for global PACLEN
        PERSIST         Probability to transmit 0-255 (64)
        PIPE            Creates a "frame pipe" to another port
        PIPEFLAG        Controls frame piping (3)
        PMSALIAS        Port override for global PMSALIAS
        PMSCALL         Port override for global PMSCALL
        PORTALIAS       Port override for global NODEALIAS
        PORTALIAS2      Secondary alias for digipeating only.
        PORTCALL        Port override for global NODECALL
        PROXY           NetRom systems to tunnel AX25 to
        QUALITY         Default NetRom neighbour quality (10)
        RESPTIME        AX25 delayed ack timer in ms (2000)
        RETRIES         Max connect/disconnect/resent attempts (10)
        RFBAUDS         RF baud rate (1200)
        SESSLIMIT       Max simultaneous connections per user (255)
        SLOTTIME        CSMA interval timer (millisecs) (100)
        SOFTDCD         Use software DCD (SCC only) (0)
        SYSOP           If 1, all users on this port are sysops (0)
        TXDELAY         Delay (ms) between PTT and start of data (300)
        TXPORT          Port on which to TX if not this one (0)
        TXTAIL          Delay (ms) between data end and PTT drop (100)
        UDPLOCAL        RX UDP port for AXUDP operations (93)
        UDPREMOTE       TX UDP port / Partners AXUDP RX port (93)
        UNPROTO         Dest & digi calls for unproto broadcasts
        USERS           Max simultaneous users on this port (255)
        VALIDCALLS      Only these callsigns allowed to connect.

        For more information on each of the above keywords, please
        refer to its page in section 7 of the manual.

</code> **EXAMPLES** <code>
        a) KISS Port, no NetRom, Pipe to port 7:
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        User-access frequency, hence NetRom linking is suppressed by
        zero QUALITY. Note the bi-directonal selective UI pipe to a
        BBS which is on port 7, allowing FBB resync requests, and the
        use of BCAST for broadcasting the BBS's mail beacons onto this
        port.

            PORT=1
                ID=144.850 MHz 1200 baud users
                INTERFACENUM=1   ; Multi-drop KISS interface
                CHANNEL=C        ; 3rd TNC
                PACLEN=160       ; Larger than default
                MAXFRAME=2       ; Smalled than default
                TXDELAY=400      ; Synth rig takes time to tx
                QUALITY=0        ; Disable NetRom on this port
                BCAST=MAIL       ; Allow mail beacons from BBS
                BCFROM=GB7PZT    ; BBS call allowed to Bcast
                PIPE=7 GB7PZT    ; Selective pipe to BBS
                PIPEFLAG=513     ; Bi-directional, UI-only
            ENDPORT


        b) APRS-only port:
        ~~~~~~~~~~~~~~~~~~

        Note the use of comment lines, an alternate IDTEXT, and the
        use of CFLAGS to disable connected mode operations, thus
        MAXFRAME, FRACK, PACLEN etc. are not needed.

            PORT=13
                ID=144.800 MHz 1200 baud APRS
                INTERFACENUM=1   ; Multidrop KISS interface
                CHANNEL=B        ; 2nd TNC
                CFLAGS=0         ; Prevent up/downlinks on this port
                DIGIFLAG=5       ; Digi only UI frames via RELAY
                MHEARD=22        ; Nice big MH list
                IDTEXT=!5224.00N/00215.00W#PHG3021 Kidder APRS digi
                ;
                ; Override default destination & path for ID beacons
                IDPATH=APRS,RELAY,WIDE
                ;
                ; Default digipeater path for APRS frames originated
                ; by APRS messaging shell and Igate.                 
                APRSPATH=RELAY
                ;                
            ENDPORT


        c) AXIP Port:
        ~~~~~~~~~~~~~

        Note the use of lower FRACK and RESPTIME because it is a
        faster link.

            PORT=8
                ID=AXIP link with WA3IP
                INTERFACENUM=2     ; Points to an AXIP interface
                IPLINK=55.73.88.69
                FRACK=2000
                RESPTIME=200
            ENDPORT


        d) AXUDP Port:
        ~~~~~~~~~~~~~~

        Illustrates the use of non-standard UDPLOCAL and UDPREMOTE, a
        hostname for IPLINK, plus lower FRACK and RESPTIME because it
        is a fast link.

            PORT=9
                ID=AXUDP link with VK1UDP
                INTERFACENUM=3           ; AXUDP interface
                IPLINK=vk1udp.ath.cx
                UDPLOCAL=9393            ; Non-standard
                UDPREMOTE=10093          ; Non-standard
                FRACK=2000
                RESPTIME=200
            ENDPORT

</code> **SEE ALSO** <code>
        IFACES(6)      -- Interfaces in XRouter.
        PORTSMORE(6)   -- PORT Directives in More Detail.
        XROUTER.CFG(8) -- Main Configuration File.

</code>
----
==== PORTSMORE ====
<code>PORTSMORE(6)            XROUTER REFERENCE MANUAL            23/10/2023
</code> **NAME** <code>
        PORTSMORE -- Port Directives In More Detail.

</code> **SYNOPSIS** <code>
        This document gives more detail on each of the PORT
        directives listed in PORTS(6). Each of these directives has
        its own section 7 MAN page, which in some cases may give
        even more detail.

</code> **APPLMASK** <code>
        Used only if XRouter is hosting applications, e.g. via the
        DEDHOST interface. Controls which applications are directly
        connectable 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, and only if those applications have either an
        APPLCALL or an APPLALIAS. 

</code> **APRSPATH** <code>
        Default digipeater path for APRS frames originated by APRS
        messaging shell and IGATE. If you omit this, the frames will
        be sent without any digipeaters. Messaging shell users may
        override this path.

        Example: APRSPATH=RELAY 

</code> **BCAST** <code>
        List of destinations for "UI broadcasting". Received non-
        digipeater UI frames, addressed to one of these destinations,
        are re-broadcasted on all ports which have a matching address
        in their BCAST list, e.g. to broadcast mail beacons from a
        BBS on one port onto several other ports.

        The callsigns must be separated by commas and there should be
        no spaces in the list.

        Example: BCAST=MAIL,ALL 

</code> **BCFROM** <code>
        Specifies a list of callsigns who may use the UI broadcast
        facility (see BCAST). BCFROM applies only to frames
        *directly* received on the port for which it is specified
        (i.e. not via digipeaters).

        If you wish to restrict the broadcast facility to certain
        senders only, list the callsigns here. If no calls are 
        specified, the facility is unrestricted. Separate the calls
        by commas, and don't include any spaces in the list.

        Example: BCFROM=GB7PZT,GB7MAX 

</code> **CFLAGS** <code>
        Controls whether or not AX25 level 2 uplinking and/or
        downlinking is allowed on the port. A typical use may be to
        prevent users from uplinking and downlinking on APRS-only
        ports. It also allows the sysop to control whether or not
        L3RTT frames are generated on inter-node links, and whether
        or not AX25 level 2 fragmentation is allowed on the port.

        Add together the decimal values of the desired options from
        this list:

                Val   Function
                -------------------------------------------------
                 1  - Allow incoming connections (uplinks).
                 2  - Allow outgoing connections (downlinks).
                 4  - Applications may downlink unconditionally.
                 8  - Suppress L3RTT generation.
                16  - Allow L2 fragmentation.

        The default value is 3, i.e. unconditional use of the port.

        Irrespective of the setting of CFLAGS, the Sysop can always
        downlink.

        Bit 2 allows applications to downlink unconditionally, i.e.
        even if users are prevented from downlinking.

        Bit 3 was provided to keep the Luddites happy, but its use
        is strongly deprecated. Setting this flag prevents L3RTT
        frames from being originated by the port if it is carrying
        an inter-node link. It will not prevent XRouter from trying
        to hold inter-node links open, as that is too much of a
        retrograde step! This bit is not set by default.  Note that
        L3RTT may also be suppressed if a route's MAXTT is 65535.

        Bit 4 allows AX25 layer 2 fragmentation if it is set. This
        is required if Forward Error Correction (FEC) is in use, to
        allow big L3 frames to be sent.

        Examples:

                CFLAGS=2  - Allow downlinking only
                CFLAGS=5  - Allow only sysops and apps to downlink.

</code> **CHANNEL** <code>
        Channel to use on interface (A-P), required only on certain
        types of multi-channel interface, e.g. KISS. Not required on
        AXIP, AXUDP, or AXTCP interfaces. Default is A.

        Example: CHANNEL=C 

</code> **CHATALIAS** <code>
        Port override for global CHATALIAS. If specified, the chat
        server will use this alias instead of the global CHATALIAS,
        on this port only.

        Example: CHATALIAS=KDRCH2 

</code> **CHATCALL** <code>
        Port override for global CHATCALL. If specified, the chat
        server will use this callsign instead of the global CHATCALL,
        on this port only.

        Example: CHATCALL=G8PZT-9 

</code> **CTEXT** <code>
        Port override for global CTEXT. This is a single line of text
        that can be sent to a caller when they connect to XRouter.
        The companion directive CTFLAGS controls which callers
        receive the text.

        If the argument specifies a filename, the contents of that
        file are read "live" every time someone connects, which may
        be of use in EMCOMM scenarios. The specified file could for
        instance be updated by another program, such as an extreme
        weather detector. See CTEXT(7) for more details.

        Examples:
            CTEXT This port is for linking only
            CTEXT /etc/weather/latest.txt

</code> **CTFLAGS** <code>
        Controls which callers are sent a "connect text" (CTEXT) when
        they connect to XRouter.

        The argument is the sum of the desired options from the
        following list:

           1 - Send CTEXT upon connection to PORTALIAS.
           2 - Send CTEXT upon connection to PORTCALL.
          
        The default value is 1 (Alias only).

</code> **CWID** <code>
        Text to send in Morse Code every 30', used only by SCC ports.
        It specifies a callsign (8 characters max.) which is sent
        every 30 minutes using Morse code. If omitted, no cwid is
        sent.

        Example: CWID=G8PZT 

</code> **DHCP** <code>
        Specifies whether or not the port IP address is obtained
        dynamically using DHCP (DHCP=1) or specified statically
        (DHCP=0). Default is 0. 

</code> **DIGIFLAG** <code>
        Controls digipeating (0=none, default=7). Options are
        enabled by adding together the following numbers:

                Value Option
            ---------------------------------------------------
              1   Digipeat UI frames
              2   Digipeat non-UI frames
              4   Enable RELAY generic digipeating (deprecated).
              8   Enable TRACE generic digipeating (deprecated).
             16   Enable WIDE generic digipeating (deprecated).
             32   Allow APRS 3rd party digi via L4.
             64   Allow digipeating to Internet (IGate).
            128   Allow digipeating from Internet (IGate).
            256   Enable UITRACE digipeating (e.g. WIDEn-n)
            512   Enable UIFLOOD digipeating (e.g. GBRn-n)

        Example: DIGIFLAG=5 ; all UI + RELAY generic.

        See APRS digipeating.... 

</code> **DIGIPORT** <code>
        Specifies the port digipeated frames are transmitted onto.
        Default is 0, i.e. the current port.

        Example: DIGIPORT=3 ; Digipeat onto port 3 

</code> **DYNDNS** <code>
        Enable / disable Dynamic DNS update client. 

</code> **ENDPORT *** <code>
        Marks the end of the PORT definition block. Subsequent
        keywords are interpreted as GLOBAL.

</code> **EXCLUDE** <code>
        EXCLUDE specifies a list of one or more callsigns from whom
        AX25 L2 frames are ignored. It would typically be used on a
        user-access port to prevent connections from trouble-makers
        and pirates.  Separate callsigns with commas, and don't
        include any spaces.

        Example: EXCLUDE=NOCALL,P1RAT ; Ignore these users

</code> **FEC** <code>
        Enable / disable Forward Error Correction.  In order to make
        use of FEC, the port needs to be using a KISS TNC with the
        CRC check disabled (PASSALL ON), or an SCC or YAM card.  The
        default is 0, i.e. disabled.
 
</code> **FRACK** <code>
        AX25 "T1" timer, i.e. frame acknowledgement time, in
        milliseconds. Default is 7000.

        After sending an AX25 packet, this is the amount of time
        XRouter waits for an "ack" before considering the packet to
        be lost.

        The T1 timer starts when the link layer dispatches the packet
        to the MAC (Media Access Control) layer, so you must allow at
        least enough time for (MAXFRAME * PACLEN) packets to be sent,
        plus an ack packet to be received, plus the other end's
        RESPTIME, plus both end's TXDELAYs, plus a generous allowance
        for channel congestion.

        A frack no less than 7000 millisecs is recommended for
        average 1200 baud links. Setting this figure too low is
        antisocial, achieves nothing, and could result in the link
        retrying out.

        However, on fast, wired (e.g. AXUDP) links, 7 seconds is
        excessive, and a figure like 2000 (2 secs) should be used.

        Example: FRACK=7000 ; 7 seconds

</code> **FREQUENCY** <code>
        Radio frequency in Hz. Default is 0. If the port is a radio
        port, this value is reported to the node mapping server, if
        such reporting is enabled.

        For non-RF ports (e.g. AXUDP) where this directive has no
        meaning and is ignored.

        Example: FREQUENCY=144925000       ; 144.925 MHz

</code> **FULLDUP** <code>
        Allow simultaneous TX/RX (SCC only). If you set FULLDUP=1,
        XRouter transmits whenever it needs to, without waiting for
        the other end to stop.

        Used only by hardware which is capable of simultaneous
        transmission and reception, such as full duplex radio or
        wire links. Default is 0 (simplex / half duplex).

        Example: FULLDUP=1   ; Full duplex 

</code> **ID *** <code>
        Mandatory text to identify port on "PORTS" display. May
        contain spaces. Please make it informative.

        Example: ID=144.825 MHz 9k6 TCP/IP users 

</code> **IDPATH** <code>
        Specifies the destination and digipeater path for ID beacons.

        The default AX25 destination and path is "ID" with no
        digipeaters. You may wish to modify this, for example on
        APRS ports, to digipeat your beacon.

        Example: IDPATH=APRS,RELAY,WIDE 

</code> **IDTEXT** <code>
        Optional ID text to use, instead of global IDTEXT, on this
        port only (e.g. for APRS ports). Only one line of text (248
        characters max.) may be specified.

        Example: IDTEXT=!5224.00N/00215.00W# (Kidder)

</code> **INITSTR** <code>
        Modem initialisation string (MODEM ports only). This is a
        string of characters sent to the modem when Xrouter is
        started.

        Example: INITSTR=ATM0

</code> **INTERFACENUM *** <code>
        Interface number this port is bound (attached) to. This
        directive is mandatory.
 
</code> **INTERLOCK** <code>
        Used only by SCC cards, because KISS TNC's make their own
        decisions about when to transmit, and XRouter has no control
        over that process.

        If a non-zero INTERLOCK value is specified, no two ports with
        the same value will transmit at the same time. Default=0.

        Example: INTERLOCK=4

</code> **IPADDRESS** <code>
        Port override for global IP address. If this is specified,
        it is used instead of the global IP address for all TCP/IP
        operations on this port.

        Example: IPADDRESS=44.131.91.5

</code> **IPLINK** <code>
        IP address or hostname of AXIP or AXUDP link partner (AXIP
        and AXUDP ports only).

        If the partner has a static IP address, it is more efficient
        to use the IP address here, otherwise it is necessary to use
        the hostname.

        Examples:

            IPLINK=62.51.67.21
            IPLINK=gb7pzt.dyndns.org

</code> **MAXFRAME** <code>
        Specifies the maximum number of frames XRouter will send to
        an AX25 partner before it must wait for an ack. The normal
        range is between 1 and 7, although maxframes of up to 127
        are allowed on modulo-128 links. The default value of
        MAXFRAME is 3.

        If you set a value between 8 and 63, XRouter attempts to use
        Modulo-128 (Extended AX25) on outgoing links. If the link
        partner is not capable of Modulo-128, the link will fall-back
        to normal AX25.

        If the port PACLEN is set to 0, XRouter dynamicallys adapts
        MAXFRAME (and PACLEN) to the link conditions, to maximise
        throughput.

        Example: MAXFRAME=4

</code> **MAXHOPS** <code>
        Specifies the maximum accepted hop count for new nodes table
        entries received via INP3 unicasts from neighbours on this
        port. Node information with hop counts that exceed this
        figure are not accepted into the nodes table. This parameter
        has no effect on data received via conventional NetRom nodes
        broadcasts.

        MAXHOPS would typically be used to limit the "hop horizon"
        to a smaller value than the default horizon, which is 30.
        Like MAXTT, it can be used to limit the number of node
        entries that are accepted via a particular port or neighbour.

        It can be overridden for individual routes using by
        "locking-in" the route at the end of XROUTER.CFG, or by a
        ROUTE ADD command in the XRNODES file or at the command
        prompt. Defaults to global MAXHOPS.

</code> **MAXTT** <code>
        Specifies the maximum accepted "trip time" (transit time)
        for new nodes table entries received via INP3 unicasts from
        neighbours on this port.

        Node information with trip times that exceed this figure are
        not accepted into the nodes table. This parameter has no
        effect on data received via conventional NetRom nodes
        broadcasts.

        MAXTT would typically be used to limit the "trip time
        horizon" to a smaller value than the default horizon, which
        is 60000 (600 seconds). Like MAXHOPS, it can be used to limit
        the number of node entries that are accepted via a particular
        port or neighbour.

        It can be overridden for individual routes using by "locking
        in" the route at the end of XROUTER.CFG, or by a ROUTE ADD
        command in the XRNODES file or at the command prompt.
        Defaults to global MAXTT.
 
</code> **MHEARD** <code>
        Enable/disable the MHEARD function on this port. The number
        specifies how many callsigns to maintain in the list. Set to
        0 to disable MHEARD. Default is 15 calls.

        Example: MHEARD=10 ; Mheard enabled, 10 calls 

</code> **MHFLAGS** <code>
        Controls which callsigns are recorded in the MHeard list,
        and defaults to 255 (record everything). The argument is the
        sum of the required options from this list:

                1    Show directly heard stations
                2    Show directly heard digipeaters
                4    Show digipeated stations

        Example: MHFLAGS=1 ; show directly heard stations only

</code> **MINQUAL** <code>
        Minimum Net/rom quality to add to node table for nodes
        received via this port. Defaults to global MINQUAL.

        Within nodes broadcasts received on that port, any node
        whose quality (after derating by port QUALITY) is less than
        the minqual will not be accepted into the nodes table.

        If specified, this overrides the global minqual, and can be
        used to exclude unreachable and marginal nodes.

        Example: MINQUAL=100 ; No nodes less than quality 100

</code> **MINTXQUAL** <code>
        Minimum NetRom node quality to include in nodes broadcasts
        on this port. Range 0 to 255, Default is 0. This is used to
        limit the size of nodes broadcasts on ports which are low
        bandwidth, low quality, or where the neighbours have limited
        nodes table capacity.

        Example: MINTXQUAL=100 ; Don't broadcast nodes with qual <100 

</code> **NETMASK** <code>
        Subnet mask used with IPADDRESS to specify which IP addresses
        are on the same network segment, and can be reached directly.
        For more information see the NETMASK command page. 

</code> **NODESINTERVAL** <code>
        Interval, in minutes, between NetRom nodes broadcasts on
        this port only. Defaults to global NODESINTERVAL.

        Whilst the Netrom network usually works on a 60 minute
        broadcast cycle, some types of software insist on a much
        smaller broadcast interval.

        It would be harmful to the established network if sysops
        tried to accommodate these neighbours by setting the global
        NODESINTERVAL to a smaller value, but using this keyword on
        a per-port basis you can keep these neighbours happy without
        disrupting the rest of the Netrom network.

        If you set NODESINTERVAL=0, XRouter ignores received nodes
        broadcasts on this port, but will allow L3/L4 activity if
        QUALITY is non-zero.

        Example: NODESINTERVAL=10 ; 10 minues between broadcasts

</code> **PACLEN** <code>
        Specifies the maximum length of the information-bearing
        portion of ax25 packets transmitted on this port only. If
        not specified, it defaults to the global PACLEN.

        All frames originating at XRouter use the global or port
        paclens specified, but Netrom frames originating at other
        systems can not be fragmented, so we have no control over
        them, and they may be larger than our paclen.

        If the port PACLEN is set to 0, Xrouter dynamicallys adapts
        PACLEN (and MAXFRAME) to the link conditions, to maximise
        throughput.

        Example: PACLEN=160 ; Allow 160 byte packets on this port

</code> **PERSIST** <code>
        PERSIST is the AX25 "Probability to transmit" in a given
        time slot (see SLOTTIME), used to minimise media contention.

        Persist should be set to (255 / (no. of users on channel)),
        e.g. for a channel with an average of 10 users on at any one
        time you would set Persist to 25. Default is 64.
 
</code> **PIPE** <code>
        Creates a "frame pipe" to another port. This allows frames
        received (and optionally sent) on this port to be copied to
        another port, e.g. to allow a PMS on one port to see the
        traffic on another port.

        Unless the "bi-directional" option (see below) is specified,
        pipes are one way. In order to have two way traffic using a
        uni-directional pipe, you must set up a reverse pipe on the
        opposite port.

        You may pipe several ports to a single destination port, but
        you can only have one *outgoing* pipe from any port.

        Pipes are capable of generating an immense amount of traffic,
        so use them with care - your target port MUST be capable of
        handling the traffic load.

        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). On a busy channel,
        this could result in lots of unnecessary traffic being piped.

        Pipes can be made "selective", by adding a comma-delimited
        callsign list, e.g. "PIPE=4 GB7PZT,KDRBBS". This reduces the
        loading on the target port, by piping only the frames with
        the specified calls 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 below).

        Pipes can be made "bi-directional" by adding 512 to the
        PIPEFLAG value (see below: suggested value = 515). If a
        frame is piped on a bi-directional pipe, the source call is
        remembered so responses can be piped back to the sender.
        Thus a reverse pipe is not needed.

        Bi-directional pipes are useful where a BBS uses XRouter as
        a "front-end" router - simply set up bi-directional selective
        pipes from each user port to the BBS port, and set up the
        BCAST option so that the UI mail headers are broadcast on
        each user port. The BBS then allows direct connects and will
        respond to resync requests.

        To disable piping, set PIPE=0 or just omit the command.

        Example: PIPE=2 ; Pipe frames from this port to port 2 

</code> **PIPEFLAG** <code>
        PIPEFLAG is only used when piping is active, and controls
        which frames are piped. The default is 3. The argument is
        the sum of the required options as follows:

            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 XRouter.
            32   - Non-UI frames transmitted by XRouter.
            64   - Allow budlisted users to be piped.
            128  - Netrom frames
            256  - IP / ARP frames
            512  - Bi-directional piping

        Example: PIPEFLAG=5 ; Pipe received UI frames only 

</code> **PMSALIAS** <code>
        Port override for global PMSALIAS

</code> **PMSCALL** <code>
        Port override for global PMSCALL

</code> **PORTALIAS** <code>
        Specifies an AX25 alias for this port, to be used in addition
        to the NODEALIAS.

        Example: PORTALIAS=KDRMIN 

</code> **PORTALIAS2** <code>
        Secondary alias for digipeating only. This callsign does not
        accept connections. 

</code> **PORTCALL** <code>
        Specifies an AX25 callsign to use on this port, in addition
        to the NODECALL.

        Example: PORTCALL=G8PZT-1

</code> **PROXY** <code>
        Remote NetRom systems to whom we will tunnel AX25 L2 frames.
        (See PROXIES page for full explanation)

        Example: PROXY=GB7PZT,GB7BBS

</code> **QUALITY** <code>
        Default quality for nodes whose broadcasts are received on
        this port (default=10). Setting this to 0 disables all
        NetRom L3/4 activity on this port.

        Example: QUALITY=30

</code> **RESPTIME** <code>
        AX25 "T2" (delayed ack) timer in milliseconds, i.e. the time
        to wait after receiving a frame, before sending an ack. This
        allows multi-frame transmissions to be acknowledged with a
        single ack, increasing link efficiency.

        Resptime should be long enough for a link partner to transmit
        a full-sized information frame, i.e. approximately
        ((their_paclen * 10000) / RFbauds) millisecs, otherwise you
        will send unnecessary ack frames.

        Too high a value will cause the link to be too "relaxed",
        whereas too low a value will cause too many acks. Both
        extremes reduce the link efficiency.

        1500 (default) is OK for 1200 bauds with paclen=120, but
        2200 would be more appropriate if their paclen was 256. At
        9600 baud, or on AXUDP links, 200 millisecs is probably
        adequate.

        Example: RESPTIME=2000 ; 2 seconds

</code> **RETRIES** <code>
        AX25 maximum consecutive connect / disconnect / resend
        attempts (default = 10).

        There is little point in setting retries more than 10, other
        than for test purposes. If you need so many retries it's a
        useless link and you're just wasting everyone else's airtime.
        The higher you set this value, the longer users will have to
        wait to get a "failure with" report for a non-contactable
        destination.

        Example: RETRIES=5

</code> **RFBAUDS** <code>
        RF baud rate (default = 1200).

        This parameter is used with "real" tnc's and YAM modems
        attached via RS232, because the RF baud rate is usually
        different to the RS232 baud rate. It simply helps XRouter
        make timing decisions (such as nodes broadcast inter-packet
        timing) and report certain stats correctly.

        Example: RFBAUDS=2400
 
</code> **SESSLIMIT** <code>
        Sesslimit specifies the maximum simultaneous connects each
        user is allowed on this port. Default is 255. This would
        typically be used to "choke" users who hog all the bandwidth
        on a port with too many connections.

        Example: SESSLIMIT=5
 
</code> **SLOTTIME** <code>
        CSMA interval timer (millisecs), used with PERSIST to make
        channel access decisions (default=100).

        If the channel is clear, the TNC (or SCC/YAM card) generates
        a random number which is compared with the PERSIST value. If
        it is less than PERSIST, the TNC waits for the SLOTTIME
        interval, then repeat the action, otherwise it transmits
        immediately.

        This improves throughput by ensuring that everyone doesn't
        transmit as soon as the channel is clear, which would cause
        collisions and retries.

        Example: SLOTTIME=100 ; 100 millisecs per slot

</code> **SOFTDCD** <code>
        Softdcd is used only by SCC cards and defaults to 0.

        If SOFTDCD=1 the real dcd will be ignored, and the SCC
        driver uses the presence of HDLC data as a DCD indication.

        Using SOFTDCD=1 with an open squelch generates a *huge*
        interrupt loading, which may cause degradation of
        performance, depending on the PC type, so it is not
        recommended.

        Example: SOFTDCD=0

</code> **SYSOP** <code>
        If you set SYSOP=1, all users who connect on this port get
        full sysop status without needing to answer a password
        challenge. This is intended ONLY FOR USE ON SECURE LINKS,
        such as RS232 or Ethernet, and the default is zero.
 
</code> **TXDELAY** <code>
        Transmit keyup delay in milliseconds (default=300).

        After keying the transmitter, the TNC (or SCC / YAM card)
        waits for this interval before sending HDLC data. This allows
        the TX to stabilise and the partner's squelch to open.

        Example: TXDELAY=500   ; Synthesiser is slow to lock

</code> **TXPORT** <code>
        Port to transmit on (default = 0 = this port).

        You would typically use this when several ports share a
        single transmitter, with separate receivers.

        Example: TXPORT=5 ; Transmit on port 5

</code> **TXTAIL** <code>
        TX turn-off delay in milliseconds (default = 100).

        This is the interval, after sending a frame, for which the
        transmitter remains active. It is intended to allow CRC and
        closing flags to be sent. It has no meaning on non-radio
        ports.

        Due to PC timing inaccuracies, you should set this no lower
        than 100 for SCC cards!

        Example: TXTAIL=100
 
</code> **UDPLOCAL** <code>
        The UDP port number for the local end of an AXUDP link. Used
        only by AXUDP ports. Default is 93. This number must match
        the link partner's UDPREMOTE, i.e. the destination service
        number in the frames from him to you.

        It is perfectly valid for all your ports to use the same
        UDPLOCAL. This reduces the number of "holes" (port forwards)
        you need to make in your firewall. The *only* reason ever to
        change UDPLOCAL from the default is when you have more than
        one AXUDP node sharing the same public IP address. Your link
        partners have no right to dictate this value!

        Example: UDPLOCAL=7388
 
</code> **UDPREMOTE** <code>
        The UDP destination number in the AXUDP frames from you to
        your link partner. It must match the link partner's UDPLOCAL,
        otherwise the link will not function.

        If not specified, UDPREMOTE defaults to 93. It is only used
        on AXUDP ports.

        You have no right to dictate this value to your link partner.
        It is THEIR choice only (see UDPLOCAL).

        Example: UDPREMOTE=10093

</code> **UNPROTO** <code>
        Destination callsign and optional digipeater string used for
        unproto broadcasts from applications on this port. Separate
        the callsigns with commas.

        Example: UNPROTO=CQ,G6YAK

</code> **USERS** <code>
        Maximum no. of simultaneous users on this port. Default is
        255 which means "no limit".

        Example: USERS=9 

</code> **VALIDCALLS** <code>
        Validcalls allows AX25 frames only from the specified
        callsigns (opposite of EXCLUDE), and is typically used to
        prevent users from connecting to link-only ports. Callsigns
        must be separated by commas, with no spaces.

        Example: VALIDCALLS=G6YAK,G6AMU ; Accept only these users 

</code> **SEE ALSO** <code>
        PORTS(6)       -- PORTs in XRouter.
        XROUTER.CFG(8) -- Main Configuration File.

</code> **PORTSMORE(6)               END OF DOCUMENT** <code>
</code>
----
==== RUNROOT ====
<code>RUNROOT(6)             XROUTER REFERENCE MANUAL              23/9/2023

</code> **NAME** <code>
        RUNROOT -- Running XRouter as Root?.

</code> **SYNOPSIS** <code>
        Running XRouter with super-user privileges is easier and
        more convenient than running it as an unprivileged user. But
        technically it is more of a security risk.

        This page explores some of the pros and cons or running
        XRouter as a privileged user or not. It is a work in
        progress...

</code> **DISCUSSION** <code>

        Running As Root:
        ~~~~~~~~~~~~~~~~

        If XRouter is "run as root" (i.e. from a root account), it
        has full access to the file system and sensitive processes.
        This makes life easier if you need to tinker with the
        operating system's configuration via XRouter's command
        interface.

        For example, imagine XRouter sitting on a remote hilltop as
        part of a Packet Radio network, but without Internet access.
        How would you set the time and date if it drifted? How would
        you make any changes to the PI's configuration, without going
        to site? There's no Internet connection, so you couldn't use
        VNC or SSH!

        Answer: If you can "connect" to XRouter over the AX25 packet
        network, and verify yourself as a sysop, you can use the DOS
        and SHELL commands to do most system maintenance, even over
        the slowest link. You could upload new versions using NFTP,
        or iff the AX25 links support TCP/IP, you might even be able
        to use XRouter's FTP server.

        But if XRouter is not running as "root", you would not be
        able to set the time or date, and you would not have write
        access to "sensitive" areas of the file system.

        The downside of running as root is that, in the unlikely
        event that a malicious actor cracks or guesses your password,
        he would have full access to the machine.

        This means he could delete all your stuff, or lock you out
        and use the machine as an attack tool.

        To get this into perspective however, XRouter has clocked up
        several years trouble-free service running as root,
        completely open to the Internet. Passwords are by far the
        weakest point, so make sure you use a strong one!

        Running Unprivileged:
        ~~~~~~~~~~~~~~~~~~~~~

        This is slightly less convenient, in that you have to tinker
        with capabilities and give some thought to what access you
        need to various parts of the system.

        But it is more secure. If someone cracked your password, they
        could only trash the XRouter part of your system.

        If you run unprivileged, you cannot change the date and time
        from the XRouter command line, and you cannot access
        privileged areas of the file system using FTP or the DOS
        emulator.

        You are also prevented from creating an EXTERNAL interface or
        performing any TCP/IP operations involving the LAN or
        localhost, unless you set CAP_NET_RAW on the program, and
        from opening low-numbered server ports on the kernal stack
        unless you set CAP_NET_BIND_SERVICE [ see CAPFLAGS(9) ].
 
</code> **SUMMARY** <code>
        Running As Root

          - Everything just works.
          - Theoretically less secure.
          - Sysop can set time and date from XRouter command line.
          - PZTDOS has full access to file system
          - FTP server has full access to file system. 

        Running As User

          - Theoretically more secure.
          - Can't access Ethernet/Wifi/localhost (*1)
          - Can't open server ports below 1024 on kernal stack (*2).
          - Sysop cannot set time or date from within XRouter
          - PZTDOS can't write to privileged parts of file system.
          - FTP server can't write to privileged parts of file system. 

            (*1) Needs CAP_NET_RAW
            (*2) Needs CAP_NET_BIND_SERVICE 

</code> **CAVEATS** <code>
        You can not use "sudo" to run XRouter as root, because the
        sudo session has a time limit. XRouter will run, but after a
        while it will stop responding to the keyboard. And it may
        bork if you use the "restart" command.

        (It is possible to change the sudo timeout on some Linux
        distros)
 
</code> **SEE ALSO** <code>
        CAPFLAGS(6)  -- Capability Flags
        IP-STACKS(6) -- IP Stacks in XRouter.
        TCP-PORTS(6) -- TCP Server Ports.
        LAN(6)       -- LAN Interfacing.

</code>
----
==== TCP-IFACE ====
<code>TCP-IFACE(6)            XROUTER REFERENCE MANUAL             28/9/2023

</code> **NAME** <code>
        TCP-IFACE -- Interface type "TCP".

</code> **DESCRIPTION** <code>
        Interface type "TCP" allows systems on the same machine, or
        on different machines, to be linked together using various
        protocols tunneled inside a TCP stream.

        This works equally well for both "datagram" and "stream"
        protocols. It can be used to connect to applications such
        a Direwolf, or to tunnel protocols through firewalls.

        A TCP interface can be either a SERVER or a CLIENT. Unlike
        the AXTCP interface it cannot be both at the same time. The
        server passively listens for connections, and the client
        actively makes connections.

        A typical TCP client interface would be defined thus:

            INTERFACE=16
                TYPE=TCP
                ID=KISSTCP (Direwolf)
                PROTOCOL=KISS
                IOADDR=127.0.0.1       ; Direwolf IP address
                INTNUM=8001            ; Direwolf TCP port
                MTU=1500
            ENDINTERFACE

        Note Some keywords are re-purposed to avoid creating new ones!

        TYPE, PROTOCOL, IOADDR, INTNUM, COM and MTU are mandatory.

        ID is an optional text which identifies the interface on
           various displays. Keep it concise. 20 chars max.

        IOADDR is used differently in client and server cases:
               In the CLIENT case, it specifies the IP address of the
               target server or app. Use 127.0.0.1 if the target is
               on the same machine as XRouter.
               In the SERVER case it must be set to 0.

        INTNUM is also used differently in client and server:
               In the CLIENT case, it specifies the TCP port of the
               target server or application.
               In the SERVER case, it specifies the TCP port the
               server is listening on.

        MTU specifies the "Maximum Transmission Unit", i.e. the
            maximum payload size for a packet transmitted on the
            interface. The value depends on the protocol.

        PROTOCOL is the protocol to use on the interface:

            ASCII    - Plain text
            AX25     - Plain AX25, no CRC
            ETHER    - Ethernet
            HDLC     - AX25 with CRC, but no HDLC flags
            IP       - Plain IP
            KISS     - Basically AX25 within SLIP
            NETROM   - Netrom backend serial link.
            PPP      - Point to Point Protocol
            SLIP     - Serial Line Internet Protocol
            TNC      - TNC Control
            TNC2     - TNC2 Emulation.

            (see PROTOCOL(7) for more detail)

        A typical TCP server interface, running KISS over TCP would
        be defined thus:

            INTERFACE=16
                TYPE=TCP
                ID=KISSTCP Server
                PROTOCOL=KISS
                IOADDR=0.0.0.0         ; 0 signifies a server
                INTNUM=3276            ; Listening TCP port
                MTU=1500
            ENDINTERFACE

</code> **NOTES** <code>
        To avoid accidental recursion, this interface uses the Linux
        IP stack. Thus if the interface is a SERVER, and INTNUM is
        below 1024, XRouter will need CAP_NET_BIND_SERVICE capability,
        or will need to run from a "root" account.

</code> **SEE ALSO** <code>
        IFACES(6)      -- Interfaces.
        CAPFLAGS(6)    -- Capability Flags.
        KISS(9)        -- KISS Protocol.
        PORTS(6)       -- Ports in XRouter.
        PPP(9)         -- Point to Point Protocol.
        PROTOCOL(7)    -- Protocol Used on INTERFACE.
        TNC2(9)        -- TNC2 Emulation.
        XROUTER.CFG(8) -- Main Configuration File.

</code>
----
==== TCP-PORTS ====
<code>TCP-PORTS(6)           XROUTER REFERENCE MANUAL              22/9/2023
</code> **NAME** <code>
        TCP-PORTS -- TCP Service Ports.

</code> **DESCRIPTION** <code>
        TCP "service ports" (not to be confused with radio ports),
        are standard or "well known" numbers between 0 and 65535
        which are used in combination with an IP address to access a
        particular process (usually a server) on a system.

        The default TCP service port numbers for XRouter's servers,
        and the corresponding configuration keywords used in
        XROUTER.CFG are as follows:

            Keyword     TCP Port    Service Name
            --------------------------------------------
            ECHOPORT           7    Echo server
            DISCARDPORT        9    Discard server
            FTPPORT           21    FTP server
            TELNETPORT        23    Telnet server
            FINGERPORT        79    Finger server
            HTTPPORT          80    HTTP server
            TTYLINKPORT       87    Raw TTY link
            RLOGINPORT       513    Remote login
            SOCKSPORT       1080    Socks proxy server
            APRSPORT        1448    APRS server
            MQTTPORT        1883    MQTT server (broker)
            TELPROXYPORT    2323    Telnet proxy server
            CHATPORT        3600    Chat server
            AGWPORT         8000    AGW TCP host API
            RHPPORT         9000    XRouter host API

        By default, all the above services are enabled, on all of
        XRouter's IP addresses. I.e. the global IPADDRESS and any
        port overrides, allowing them to be used by TCP/IP over
        AX25, TCP/IP over SLIP/PPP etc..

        If you are *not* using the EXTERNAL interface to share the
        Ethernet or WiFi adaptors, the default case is that these
        services will also be available via the Linux kernal IP
        addresses.

        If you *are* using the EXTERNAL interface to share the
        Ethernet or WiFi adaptors, these services will NOT be
        available via the Linux kernal IP addresses unless you
        explicitly say so (see below).

        See LAN(9) for more information on using the EXTERNAL
        interface. 


        Overriding Default TCP Service Ports
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        You may wish to disable services, or change their TCP port.

        For instance, you may need to move the Telnet port if you
        have another process using TCP port 23 on the same machine.
        Or you may wish to disable the SOCKS server because you don't
        need it.

        You may also choose to make some services available on
        XRouter's TCP/IP stack and not on Linux stack, or vice versa.

        To override the default, use one or more of the above
        configuration keywords in the GLOBAL section of XROUTER.CFG.

        If you use the keyword without an argument, or with an
        argument of zero, that service is disabled, for example, the
        following formats disable the Telnet server on both XRouter
        and Linux IP stacks:

                TELNETPORT=
                TELNETPORT=0

        If you use the keyword with a single argument, the result
        depends on whether you are using the EXTERNAL interface or
        not.

        If you *are* using the EXTERNAL interface, the argument
        applies only to the XRouter stack.

        If you are *not* using the EXTERNAL interface, the argument
        applies to BOTH stacks.

        With those rules in mind, the following example moves the
        Telnet server from the default port (23), to port 88:

                TELNETPORT=88

        If you supply TWO arguments, the first *always* applies to
        XRouter's stack and the second *always* applies to the Linux
        stack. 

        You may supply different numbers for each stack, or disable
        one and not the other.  The numbers must be separated by
        whitespace, NOT commas.

        For example, the following specifies that the TELNET server
        shall use TCP port 88 on XRouter's TCP/IP stack, and port 89
        on the Linux stack:

                TELNETPORT=88 89

        This one disables the Telnet server on XRouter's TCP/IP
        stack, whilst enabling it for port 88 on the Linux stack:

                TELNETPORT=0 88

        Finally, this example enables the Telnet server on port 88 of
        XRouter's TCP/IP stack, whilst disabling it on Linux stack: 

                TELNETPORT=88 0

</code> **CAVEATS** <code>
        Unless you run XRouter with root privileges, or grant it the
        CAP_NET_BIND_SERVICE capability, you will NOT be able to open
        any port number less than 1024 on the Linux stack.

        In such a case, a directive like this:

             RLOGINPORT=0 513

        will return an error like this:

             Error 13 opening RLogin server port 513

        Moving the port above 1023, e.g. 7513 would solve the
        problem, so long as you can remember the port number!

        If you want to use ports below 1024, and you don't want to
        run XRouter with root privileges, you can use setcap to set
        the CAP_NET_BIND_SERVICE capability as follows (assuming the
        xrouter executable is "xrpi"):

            sudo setcap cap_net_bind_service=pe xrpi

        This will overwrite any previous capability set on that file,
        so if you are using the EXTERNAL interface, you need to set
        the CAP_NET_RAW capability at the same time, as follows:

            sudo setcap cap_net_raw,cap_net_bind_service=pe xrpi

        Another option is to use rinetd to redirect connections to a
        higher port number. For instance the following line in
        rinetd's configuration:

            192.168.0.10    513      127.0.0.1   8000

        would forward connections for port 513 on address
        192.168.0.10 to localhost port 8000 which XRouter can listen
        on even without root privileges.

        Finally, you could simply disable the port on the Linux
        stack, for example:

            TELNETPORT=23 0

</code> **SEE ALSO** <code>
        CAPFLAGS(6)    -- Capability Flags.
        IP-STACKS(6)   -- TCP/IP Stacks in XRouter.
        LAN(6)         -- LAN Interfacing.
        RUNROOT(6)     -- Run as Root or Not?
        SERVERS(9)     -- Servers in XRouter.
        XROUTER.CFG(8) -- Main Configuration File.

</code>
----
==== TUN-IFACE ====
<code>TUN-IFACE(6)           XROUTER REFERENCE MANUAL               6/9/2023

</code> **NAME** <code>
        TUN-IFACE -- Tunnel Interface.

</code> **DESCRIPTION** <code>
        The Linux "tun" interface provides a means of IP-layer
        communication between user-space programs such as XRouter,
        and the Linux kernal IP stack.

        It is a purely software interface; there is no hardware
        involved.

        Tunnels may be "transient", or "persistent".

        A transient tunnel is one that is created, used and destroyed
        by the same program. It ceases to exist when the program
        closes.

        A persistent tunnel is one that is created from the Linux
        command line using a command such as this:

              "ip tuntap add mode tun dev tun7".

        Programs can attach to, and detach from, a persistent tunnel
        at will. The tunnel is not destroyed when the user-space
        program closes.

        XRouter can use either type of tunnel.

        Tunnels may only be created or modified by root users, or
        those with CAP_NET_ADMIN capability.


        Usage Cases:
        ============

        In most cases, XRouter communicates with the outside world
        either via the Linux TCP/IP stack, via its own TCP/IP stack,
        or via serial RS232 interfaces.

        It can also be set up to allow PING, TELNET, FTP, HTTP etc
        from Linux to XRouter, and to access Linux services from
        XRouter. But those interactions are done at a layer ABOVE the
        network layer. There is normally no IP-layer communication
        between XRouter and the Linux TCP/IP stack. I.e. you can't
        normally send an IP datagram from XRouter to Linux or vice
        versa.

        (Note: It is possible for XR32 to do this on Windows when
        using the NDIS driver to share the Ethernet NIC. But Linux
        appears to ignore XRouter's Ethernet frames that are sent on
        a shared NIC because the source and destination hardware
        addresses are the same. Maybe there's a fix for this?)

        Because of the above, direct IP routing between XRouter and
        other programs on the same Linux machine is not possible.

        Usually this can be circumvented using AXIP, AXUDP or IPUDP
        via the Linux localhost address space. But some programs,
        e.g. JNOS, don't seem able to access that space.

        Another alternative would be to use SLIP, but that
        functionality has been withdrawn from Linux and JNOS.

        This is where an IP tunnel can be used.

</code> **OPTIONS** <code>
        Configuring a Tunnel Interface on XRouter:
        ======================================

        Using a Persistent Tunnel
        ~~~~~~~~~~~~~~~~~~~~~~~~~

        Let's say the tunnel's name is "tun99" and it has the
        "address" 192.168.0.100 and "destination" 192.168.0.99. The
        former is the IP address of the Linux end, and the latter is
        the XRouter end.

        In XROUTER.CFG, define an interface with TYPE=TUN and
        COM=tun99 like this:

            INTERFACE=1
                ID=Tunnel to Linux
                TYPE=TUN
                COM=tun99
                PROTOCOL=IP
                MTU=1500
            ENDINTERFACE

        Then attach a single port to that interface, with an IP
        address that matches the *destination* address of the tunnel.
        (If the addresses don't match, XRouter will not receive
        frames!).

            PORT=3
                ID="Tunnel"
                INTERFACENUM=1
                ipaddress=192.168.0.99
            ENDPORT

        Finally, add some routing to IPROUTE.SYS, so XRouter knows
        where to send IP datagrams. For example:

            IP ROUTE ADD 192.168.0.0/24 192.168.0.100 3 d

        That routes all of 192.168.x.x to the gateway 192.168.0.100,
        whch is at the "far" end of the tunnel from XRouter's point
        of view.


        Using a transient tunnel:
        ~~~~~~~~~~~~~~~~~~~~~~~~~

        In this case the tunnel is created and named by XRouter, and
        lasts only until XRouter is closed.

        The XRouter interface and port are defined in the same way as
        for the persistent tunnel, but a few variations are possible.

        In all cases, the IP address for the "local" (XRouter) end of
        the tunnel is specified by IPADDRESS in the PORT block, and
        you will needs to set up a suitable route in IPROUTE.SYS.

        a) Simple Method

        If you add IOADDR keyword to the INTERFACE block (see below),
        it specifies the IP address at the *far* (Linux) end of the
        tunnel. XRouter will create the tunnel and set both addresses:

            INTERFACE=3
                ID=Tunnel to Linux
                TYPE=TUN
                COM=tun99
                PROTOCOL=IP
                IOADDR=192.168.0.98 <--- Add this line
                MTU=1500
            ENDINTERFACE


        b) Manual Method

        If you OMIT the IOADDR keyword, you are responsible for
        setting up the addresses at BOTH ends of the tunnel, and for
        bringing it "up" (online).

        You can do this manually, by typing commands into a Linux
        terminal after XRouter has started, or you can put "shell"
        commands in BOOTCMDS.SYS like this:

        # Assign the address 192.168.0.98 to the Linux end of tun99:
        shell ip address add 192.168.0.98 dev tun99
        ;
        # Wait 300 millisecs for Linux to execute the command
        wait 300
        #
        # Tell Linux that 192.168.0.99 is on the other end of tun99:
        shell ifconfig tun99 dstaddr 192.168.0.99
        #
        wait 300
        #
        # Bring up the Linux end of the interface:
        shell ip link set dev tun99 up
        #

        There are many ways in Linux of achieving the same results,
        for instance (all on one line):

            ifconfig tun99 192.168.0.98 pointopoint 192.168.0.99
               mtu 1500 up

</code> **SEE ALSO** <code>
        IFACES(6)       -- Interfaces in XRouter.
        CAPFLAGS(6)     -- Capability Flags.
        PORTS(6)        -- Ports in XRouter.
        BOOTCMDS.SYS(8) -- Boot-time commands
        XROUTER.CFG(8)  -- Main Configuration File.

</code>
----
==== UDP-IFACE ====
<code>UDP-IFACE(6)            XROUTER REFERENCE MANUAL             28/9/2023

</code> **NAME** <code>
        UDP-IFACE -- Interface type "UDP".

</code> **DESCRIPTION** <code>
        Interface type "UDP" allows systems on the same machine, or
        on different machines, to be linked together using various
        protocols tunneled inside UDP datagrams.

        Whilst intended for "frame-delimited" protocols, it has been
        found to work satisfactorily with "stream" protocols, at
        least on the same machine.

        A typical UDP interface would be defined thus:

            INTERFACE=17
                TYPE=UDP
                ID=KISS over UDP
                PROTOCOL=KISS
                IOADDR=127.0.0.1
                INTNUM=9701
                COM=9702
                MTU=256
            ENDINTERFACE

        Note Some keywords are re-purposed to avoid creating new ones!

        TYPE, PROTOCOL, IOADDR, INTNUM, COM and MTU are mandatory.

        ID is an optional text which identifies the interface on
           various displays. Keep it concise. 20 chars max.

        IOADDR specifies the IP address of the target system, i.e.
               the other end of the link. Use 127.0.0.1 if the target
               is on the same machine as XRouter.

        COM specifies the UDP port the target system listens on.

        INTNUM specifies the UDP port that XRouter is listening on.
               If both systems are on the same machine, COM and
               INTNUM *must* be different!!

        MTU specifies the "Maximum Transmission Unit", i.e. the
            maximum payload size for a packet transmitted on the
            interface. The value depends on the protocol.

        PROTOCOL is the protocol to use on the interface:

            ASCII    - Plain text
            AX25     - Plain AX25, no CRC
            ETHER    - Ethernet
            HDLC     - AX25 with CRC, but no HDLC flags
            IP       - Plain IP
            KISS     - Basically AX25 within SLIP
            NETROM   - Netrom backend serial link.
            PPP      - Point to Point Protocol
            SLIP     - Serial Line Internet Protocol
            TNC      - TNC Control
            TNC2     - TNC2 Emulation.

            (see PROTOCOL(7) for more detail)
</code> **NOTES** <code>
        This interface uses the Linux IP stack, so if INTNUM is below
        1024, XRouter will need CAP_NET_BIND_SERVICE capability, or
        will need to run from a "root" account.

</code> **SEE ALSO** <code>
        IFACES(6)      -- Interfaces.
        CAPFLAGS(6)    -- Capability Flags.
        KISS(9)        -- KISS Protocol.
        PORTS(6)       -- Ports in XRouter.
        PPP(9)         -- Point to Point Protocol.
        PROTOCOL(7)    -- Protocol Used on INTERFACE.
        TNC2(9)        -- TNC2 Emulation.
        XROUTER.CFG(8) -- Main Configuration File.

</code>
----