======Section 6 - Installation and Configuration Topics====== ==== AGWHOST ==== AGWHOST(6) XROUTER REFERENCE MANUAL 27/9/2023 **NAME** AGWHOST -- AGW Application Support. **DESCRIPTION** 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 **SEE ALSO** 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. ---- ==== AGW-IFACE ==== AGW-IFACE(6) XROUTER REFERENCE MANUAL 27/9/2023 **NAME** AGW-IFACE -- AGW Packet Engine Interface. **DESCRIPTION** 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 **SEE ALSO** 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. ---- ==== ASYNC-IFACE ==== ASYNC-IFACE(6) XROUTER REFERENCE MANUAL 23/9/2023 **NAME** ASYNC -- Interface Type "ASYNC" **DESCRIPTION** 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. **SEE ALSO** IFACES(6) -- Interfaces. PORTS(6) -- Ports. PROTOCOL(7) -- Protocol Used on INTERFACE. XROUTER.CFG(8) -- Main Configuration File. ---- ==== AXIP-IFACE ==== AXIP-IFACE(6) XROUTER REFERENCE MANUAL 26/9/2023 **NAME** AXIP-IFACE -- Interface Type "AXIP". **DESCRIPTION** 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 **NOTES** 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. **CAVEATS** 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! **SEE ALSO** 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. ---- ==== AXTCP-IFACE ==== AXTCP-IFACE(6) XROUTER REFERENCE MANUAL 29/9/2023 **NAME** AXTCP-IFACE -- Interface Type "AXTCP". **DESCRIPTION** 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= is the NetRom "alias" of the server , and 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. **NOTES** 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. **SEE ALSO** 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. ---- ==== AXUDP-IFACE ==== AXUDP-IFACE(6) XROUTER REFERENCE MANUAL 26/9/2023 **NAME** AXUDP-IFACE -- Interface Type "AXUDP". **DESCRIPTION** 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 **NOTES** 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. **CAVEATS** 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. **SEE ALSO** 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. ---- ==== CAPFLAGS ==== CAPFLAGS(6) XROUTER REFERENCE MANUAL 23/9/2023 **NAME** CAPFLAGS -- Capability Flags **DESCRIPTION** 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. **EXAMPLES** 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 **CAVEATS** 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. **SEE ALSO** 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? ---- ==== COLOURS ==== COLOURS(6) XROUTER REFERENCE MANUAL 25/10/2023 **NAME** COLOURS -- Display Colours. **DESCRIPTION** 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. **SEE ALSO** CONSOLES(6) -- About XRouter Consoles. XROUTER.CFG(8) -- Main Configuration File. ---- ==== CONSOLES ==== CONSOLES(6) XROUTER REFERENCE MANUAL 26/9/2023 **NAME** CONSOLES -- About XRouter Conoles. **INTRODUCTION** 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. **CONSOLE LAYOUT** 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. **CONSOLE KEYS** The following "special" keys are available when a console is displayed: Display console help window. Toggle monitoring on/off (MON). Select port(s) to monitor. (MPORT) Select monitored protocols. (MMASK) Toggle disk capture on/off. Cancel operation / Disconnect. L/R arrow Select previous / next console. U/D arrow Scroll back/forward by one line. / Scroll back/forward by one page. End scrollback. Previous command in history. Next command in history. / ALT-M Open menu. Clear screen. Exit program. - Help Pressing pops up a dialog with the above information on it. The 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 key. - MON - Monitoring The key provides a quick way to toggle monitoring (protocol tracing) on and off, and is a shortcut for the MON ON|OFF commands. - 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 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 KEY. - Monitor Mask The key invites you to enter the "monitor mask" (aka trace mask), i.e. the protocols you wish to monitor. Pressing 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. - Disk capture The 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 (MMASK) and (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. - Cancel / Disconnect The key "backtracks" if you have pressed , or . It can also be used to immediately disconnect a console session. **SELECTING CONSOLES** 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. **WINDOW MENU** On XRPi/XRLin, pressing and together temporarily replaces the console status bar with a grey "menu bar". On XRWin the 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 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 , the menu is closed and the console top status bar returns. **FILE MENU** 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. **VIEW MENU** 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 **HELP MENU** "(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. **COMMAND HISTORY** Each console remembers the last 5 commands used on that console. These can be selected using the and keys, and actioned by hitting **REVIEW MODE** 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 , and 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. **LANGUAGES** 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. **CONFIGURATION** 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 , 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 key. MPORTS This is the combination of PORTs which will be monitored (traced) by default, until changed by an MPORT command or the 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 **SEE ALSO** 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. ---- ==== EXTERN-IFACE ==== EXTERN-IFACE(6) XROUTER REFERENCE MANUAL 26/9/2023 **NAME** EXTERN-IFACE -- Interface Type "EXTERNAL". . **DESCRIPTION** 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. **CAVEATS** 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. **SEE ALSO** 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. ---- ==== IFACES ==== IFACES(6) XROUTER REFERENCE MANUAL 23/9/2023 **NAME** IFACES -- Interfaces in XRouter. **DESCRIPTION** 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 **OPTIONS** 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 **EXAMPLES** 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 **SEE ALSO** 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 ---- ==== IP-STACKS ==== IP-STACKS(6) XROUTER REFERENCE MANUAL 22/9/2023 **NAME** IP-STACKS -- TCP/IP Stacks in XRouter. **DESCRIPTION** 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. **SEE ALSO** IP(1) -- IP Configuration Commands. IPROUTE.SYS(8) -- IP Configuration & Routing File. IP-PRIMER(9) -- IP Primer. ---- ==== LAN ==== LAN(6) XROUTER REFERENCE MANUAL 23/9/2023 **NAME** LAN -- LAN Interfacing. **DESCRIPTION** 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 **CAVEATS** 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. **SEE ALSO** 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. ---- ==== LOOP-IFACE ==== LOOP-IFACE(6) XROUTER REFERENCE MANUAL 26/9/2023 **NAME** LOOP-IFACE -- Interface type "LOOPBACK". **DESCRIPTION** 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) **EXAMPLE** # 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 # **SEE ALSO** 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. ---- ==== PORTS ==== PORTS(6) XROUTER REFERENCE MANUAL 26/9/2023 **NAME** PORTS -- PORTS in XRouter. **DESCRIPTION** 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 =, 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: **OPTIONS** 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. **EXAMPLES** 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 **SEE ALSO** IFACES(6) -- Interfaces in XRouter. PORTSMORE(6) -- PORT Directives in More Detail. XROUTER.CFG(8) -- Main Configuration File. ---- ==== PORTSMORE ==== PORTSMORE(6) XROUTER REFERENCE MANUAL 23/10/2023 **NAME** PORTSMORE -- Port Directives In More Detail. **SYNOPSIS** 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. **APPLMASK** 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. **APRSPATH** 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 **BCAST** 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 **BCFROM** 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 **CFLAGS** 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. **CHANNEL** 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 **CHATALIAS** 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 **CHATCALL** 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 **CTEXT** 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 **CTFLAGS** 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). **CWID** 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 **DHCP** Specifies whether or not the port IP address is obtained dynamically using DHCP (DHCP=1) or specified statically (DHCP=0). Default is 0. **DIGIFLAG** 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.... **DIGIPORT** Specifies the port digipeated frames are transmitted onto. Default is 0, i.e. the current port. Example: DIGIPORT=3 ; Digipeat onto port 3 **DYNDNS** Enable / disable Dynamic DNS update client. **ENDPORT *** Marks the end of the PORT definition block. Subsequent keywords are interpreted as GLOBAL. **EXCLUDE** 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 **FEC** 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. **FRACK** 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 **FREQUENCY** 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 **FULLDUP** 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 **ID *** Mandatory text to identify port on "PORTS" display. May contain spaces. Please make it informative. Example: ID=144.825 MHz 9k6 TCP/IP users **IDPATH** 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 **IDTEXT** 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) **INITSTR** Modem initialisation string (MODEM ports only). This is a string of characters sent to the modem when Xrouter is started. Example: INITSTR=ATM0 **INTERFACENUM *** Interface number this port is bound (attached) to. This directive is mandatory. **INTERLOCK** 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 **IPADDRESS** 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 **IPLINK** 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 **MAXFRAME** 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 **MAXHOPS** 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. **MAXTT** 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. **MHEARD** 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 **MHFLAGS** 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 **MINQUAL** 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 **MINTXQUAL** 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 **NETMASK** 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. **NODESINTERVAL** 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 **PACLEN** 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 **PERSIST** 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. **PIPE** 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 **PIPEFLAG** 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 **PMSALIAS** Port override for global PMSALIAS **PMSCALL** Port override for global PMSCALL **PORTALIAS** Specifies an AX25 alias for this port, to be used in addition to the NODEALIAS. Example: PORTALIAS=KDRMIN **PORTALIAS2** Secondary alias for digipeating only. This callsign does not accept connections. **PORTCALL** Specifies an AX25 callsign to use on this port, in addition to the NODECALL. Example: PORTCALL=G8PZT-1 **PROXY** Remote NetRom systems to whom we will tunnel AX25 L2 frames. (See PROXIES page for full explanation) Example: PROXY=GB7PZT,GB7BBS **QUALITY** 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 **RESPTIME** 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 **RETRIES** 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 **RFBAUDS** 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 **SESSLIMIT** 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 **SLOTTIME** 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 **SOFTDCD** 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 **SYSOP** 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. **TXDELAY** 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 **TXPORT** 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 **TXTAIL** 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 **UDPLOCAL** 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 **UDPREMOTE** 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 **UNPROTO** Destination callsign and optional digipeater string used for unproto broadcasts from applications on this port. Separate the callsigns with commas. Example: UNPROTO=CQ,G6YAK **USERS** Maximum no. of simultaneous users on this port. Default is 255 which means "no limit". Example: USERS=9 **VALIDCALLS** 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 **SEE ALSO** PORTS(6) -- PORTs in XRouter. XROUTER.CFG(8) -- Main Configuration File. **PORTSMORE(6) END OF DOCUMENT** ---- ==== RUNROOT ==== RUNROOT(6) XROUTER REFERENCE MANUAL 23/9/2023 **NAME** RUNROOT -- Running XRouter as Root?. **SYNOPSIS** 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... **DISCUSSION** 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) ]. **SUMMARY** 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 **CAVEATS** 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) **SEE ALSO** CAPFLAGS(6) -- Capability Flags IP-STACKS(6) -- IP Stacks in XRouter. TCP-PORTS(6) -- TCP Server Ports. LAN(6) -- LAN Interfacing. ---- ==== TCP-IFACE ==== TCP-IFACE(6) XROUTER REFERENCE MANUAL 28/9/2023 **NAME** TCP-IFACE -- Interface type "TCP". **DESCRIPTION** 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 **NOTES** 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. **SEE ALSO** 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. ---- ==== TCP-PORTS ==== TCP-PORTS(6) XROUTER REFERENCE MANUAL 22/9/2023 **NAME** TCP-PORTS -- TCP Service Ports. **DESCRIPTION** 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 **CAVEATS** 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 **SEE ALSO** 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. ---- ==== TUN-IFACE ==== TUN-IFACE(6) XROUTER REFERENCE MANUAL 6/9/2023 **NAME** TUN-IFACE -- Tunnel Interface. **DESCRIPTION** 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. **OPTIONS** 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 **SEE ALSO** 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. ---- ==== UDP-IFACE ==== UDP-IFACE(6) XROUTER REFERENCE MANUAL 28/9/2023 **NAME** UDP-IFACE -- Interface type "UDP". **DESCRIPTION** 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) **NOTES** 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. **SEE ALSO** 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. ----