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(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(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(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(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=<alias> <hostname | ipaddr> <tcp_port>
<alias> is the NetRom "alias" of the server
<hostname>, <ipaddr> and <tcp_port> are those of the
server
You may specify additional servers, by including a CONFIG for
each one. There is no limit to the number of CONFIG
directives that can be used with a single interface.
Combined AXTCP Client/Server Interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A combined interface is specified by including both INTNUM and
CONFIG directives. For example, this combines a server
listening on TCP port 9393 with 3 client connections:
INTERFACE=5
TYPE=AXTCP
INTNUM=9393
MTU=256
CONFIG=DORSET 216.23.45.91 10093
CONFIG=WALES gw3xr.dyndns.org 9394
CONFIG=Brum bm23.ath.cx 7507
ENDINTERFACE
This is just an example, and it could only be used at a
"static" node, in which case the client connections could
be replaced by AXIP or AXUDP anyway.
Such a configuration *couldn't* be used for "mobile" node,
because there's no way of directing incoming TCP port 9393 to
a mobile server!
AXTCP PORT Settings
~~~~~~~~~~~~~~~~~~~
A PORT attached to an AXTCP interface needs no special
configuration, and should simply be configured with
parameters (FRACK, RESPTIME, RFBAUDS) appropriate to a high
speed connection, for example:
PORT=8
ID=AXTCP Operations
INTERFACENUM=5
FRACK=2000
RESPTIME=200
RFBAUDS=56000
ENDPORT
MAC parameters such as TXDELAY, TXTAIL, SLOTTIME, PERSIST,
FULLDUP, SOFTDCD etc. are meaningless for AXUDP, but FRACK,
RESPTIME, PACLEN, MAXFRAME, QUALITY etc. operate as normal.
On fast internet links you may wish to use a much lower FRACK,
say 2000ms, than on radio. It is not recommended that you
reduce it much below 1000ms, as it needs to be *at least*
twice the worst round-trip time plus the other end's RESPTIME.
RESPTIME is probably the one which will have most effect on
the responsiveness of the AX25 link, because it controls the
time delay between receiving a packet and sending an ACK. It
should be just a little more than the time it takes to receive
a maximum length packet. For example, at a data rate of
56Kbits/sec, a 256 byte packet lasts less than 50msec, so
RESPTIME=50 would be adequate. However the timing jitter due
to operating under Windows means that RESPTIME should be more
like 200ms.
By default, all AXTCP connections use the same PORT, but if
you prefer to use one port per neighbour, see the following
section. You must NOT attach more than one PORT to an AXTCP
interface.
Multiple Interfaces / Ports
~~~~~~~~~~~~~~~~~~~~~~~~~~~
A single AXTCP server can accommodate many clients, so there
is no practical need to use more than one AXTCP interface and
port.
This is analogous to having several nodes on the same radio
frequency, except that the nodes don't see each other's
transmissions, and there is no "hidden station" effect.
You may however prefer to assign each AXTCP partner to a
seperate port, analogous to having a dedicated radio
frequency for each neighbour. In this case you may configure
several interfaces, each with a single PORT attached.
The only proviso is that no two AXTCP interfaces may use the
same INTNUM.
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(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(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(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(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:
<F1> Display console help window.
<F2> Toggle monitoring on/off (MON).
<F3> Select port(s) to monitor. (MPORT)
<F4> Select monitored protocols. (MMASK)
<F5> Toggle disk capture on/off.
<ESC> Cancel operation / Disconnect.
L/R arrow Select previous / next console.
U/D arrow Scroll back/forward by one line.
<PgUp>/<PgDn> Scroll back/forward by one page.
<End> End scrollback.
<Ctrl-LeftArrow> Previous command in history.
<Ctrl-rightArrow> Next command in history.
<Alt> / ALT-M Open menu.
<Alt-C> Clear screen.
<Alt-X> Exit program.
<F1> - Help
Pressing <F1> pops up a dialog with the above information on
it. The <ESC> key closes that dialog when you've finished
with it.
The contents of the help window are context-sensitive, i.e.
they vary according to what you were doing when you pressed
the <F1> key.
<F2> - MON - Monitoring
The <F2> key provides a quick way to toggle monitoring
(protocol tracing) on and off, and is a shortcut for the
MON ON|OFF commands.
<F3> - MPORT - "Monitor port"
The F3 key selects the port(s) to be monitored (traced), and
is a shortcut for the MPORT command.
Upon pressing this key you are invited to enter a number or
string of numbers representing the combination of ports to
monitor. If you press <F1> at this point a pop-up help
window will show you the following information:
To select port(s) to monitor, add together the following hex
values:
Port HEX Port HEX Port HEX Port HEX
------------------------------------------------------
0 1 8 100 16 10000 24 1000000
1 2 9 200 17 20000 25 2000000
2 4 10 400 18 40000 26 4000000
3 8 11 800 19 80000 27 8000000
4 10 12 1000 20 100000 28 10000000
5 20 13 2000 21 200000 29 20000000
6 40 14 4000 22 400000 30 40000000
7 80 15 8000 23 800000 31 80000000
e.g. #12 will monitor ports 4 and 1.
Alternatively you may enter a single decimal port number,
or a combination of ports separated by "+" e.g. "1+5+23".
You may cancel the operation by pressing the <ESC> KEY.
<F4> - Monitor Mask
The <F4> key invites you to enter the "monitor mask" (aka
trace mask), i.e. the protocols you wish to monitor.
Pressing <F1> at this point pops up a help window with the
following information:
0001 - Incoming frames 0100 - ICMP
0002 - Outgoing frames 0200 - TCP
0004 - AX25 layer 2 0400 - KISS
0008 - AX25 info frames 0800 - SLIP
0010 - AX25 layer 3 1000 - PASSALL
0020 - AX25 layer 4 2000 - Hex Dump
0040 - IP frames
0080 - ARP frames
To select protocols, add together the desired hex flags from
the above list. For example 0201 will show incoming TCP
segments only, while 0241 will show the underlying IP
datagrams as well. The default setting is 03FF, which shows
all incoming and outgoing traffic from AX25 layer 2 upwards.
The MMASK command has the same function.
<F5> - Disk capture
The <F5> key toggles disk capture on and off, and is a
shortcut for the CAP[TURE] command.
When capture is enabled, anything which is displayed in the
central window of an XRouter console is also written to disk.
This includes session activity and TRACE'd data. You can
make it more specific using <F4> (MMASK) and <F3> (MPORT).
Whereas the screen display is filtered to prevent it being
garbled by binary data, the capture is pure binary, so it is
useful for diagnostics.
There is a seperate capture file for each XRouter "console",
named CAPTUREnn.TXT where nn represents the console number
(01 to 05). The capture files are created in the XRouter
working directory. Although they have the extension ".TXT"
to enable them to be easily opened with a text editor, they
may somtimes contain characters which simple text editors
can't display.
Capture is fully independent on each console, and consoles
may be captured concurrently. Switching between consoles, or
scrolling consoles back, does not affect the capture.
<ESC> - Cancel / Disconnect
The <ESC> key "backtracks" if you have pressed <F1>, <F3> or
<F4>. It can also be used to immediately disconnect a
console session.
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 <ALT> and <M> together temporarily
replaces the console status bar with a grey "menu bar". On
XRWin the <ALT> key by itself performs the same function.
The menu bar currently has (F)ile (V)iew and (H)elp options,
which can be navigated using the arrow keys, and actioned
using the <RETURN> key.
One character of each menu item is highlighted in red,
indicating that it is a "hot key". Pressing the highlighted
key causes that menu item to be actioned. For example ALT-M
followed by "V" takes you into the (V)iew menu, from where
pressing the "N" key takes you to the nodes monitor window.
Or you can simply type ALT-V followed by "N".
Upon actioning a menu item or pressing <ESC>, the menu is
closed and the console top status bar returns.
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 <Ctrl-LeftArrow>
and <Ctrl-RightArrow> keys, and actioned by hitting <RETURN>
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 <PgUp>, <PgDn> and <End> keys. The only indication of
review mode is the caption on the bottom menu bar.
The console won't receive anything else while you are in
review mode. However, if you are capturing to file, the
capture is not interrupted by review mode.
The default size of the review buffer is 400 lines of text,
which is in addition to the current page. Thus if the
console height is 50 lines, you can review the last 9 pages
of activity. The size of the review buffer can be altered
using the REVIEW directive, either (for all consoles) in the
global section of XROUTER.CFG, or (for individual consoles)
within a CONSOLE definition block.
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 <enter>, the text is "echoed" into the main window
using the ECHOCOLOR. This colour is chosen by default to be
bright, and to be different from the other colours used in
that window, to make it easy for the sysop to differentiate
between sent and received text.
MMASK
This is the "monitor mask" (aka trace mask) which determines
which protocols are traced by default. The mask is the sum
of the desired hex values from the following list:
0001 - Incoming frames 0100 - ICMP
0002 - Outgoing frames 0200 - TCP
0004 - AX25 layer 2 0400 - KISS
0008 - AX25 info frames 0800 - SLIP
0010 - AX25 layer 3 1000 - PASSALL
0020 - AX25 layer 4 2000 - Hex Dump
0040 - IP frames
0080 - ARP frames
E.g. 0201 shows incoming TCP segments only, while 0241 shows
the underlying IP datagrams as well. The default setting is
03FF, which shows all incoming and outgoing traffic from
AX25 layer 2 upwards. The sysop may override this at any
time using the MMASK command or the <F4> key.
MPORTS
This is the combination of PORTs which will be monitored
(traced) by default, until changed by an MPORT command or
the <F3> key. The default is to monitor ALL ports, but you
may wish to limit this to the main ports of interest.
The argument is either a HEX number between 0 and FFFFFFFF,
a list of port numbers, or the words ALL or NONE. The hex
value is calculated by adding together the desired values
from this table:
Port HEX Port HEX Port HEX Port HEX
------------------------------------------------------
0 1 8 100 16 10000 24 1000000
1 2 9 200 17 20000 25 2000000
2 4 10 400 18 40000 26 4000000
3 8 11 800 19 80000 27 8000000
4 10 12 1000 20 100000 28 10000000
5 20 13 2000 21 200000 29 20000000
6 40 14 4000 22 400000 30 40000000
7 80 15 8000 23 800000 31 80000000
However, it is usually more convenient to specify a list of
port numbers. These may be supplied either as a series of
single numbers, or in one or more ranges, or as combinations
of the two. For example: MPORTS=1,3-5,8,10-12. There must be
no spaces in the list.
REVIEW
This specifies the number of lines of scrollback available
on the console. The value is a compromise, because setting a
large value may increase the CPU usage and/or slow down the
scrolling. The default is 400 lines, which is 8 pages on a
50 line console.
NUMCONSOLES
The total number of consoles defaults to 3. This may be
changed using the NUMCONSOLES=n directive in the global
section of XROUTER.CFG, where n is a number between 0 and 5.
CONSOLE Definition Blocks
Console definition blocks are used to specify any
characteristics of consoles that differ from the default. If
all the consoles are to be identical, you can simply define
the characteristics in the GLOBAL section of XROUTER.CFG.
Only those characteristics that differ from the defaults
need to be specified.
Console definition blocks start with CONSOLE=n where n is a
number between 1 and 5, and end with ENDCONSOLE. They may
contain any or all of the keywords listed above (except
NUMCONSOLES). There should be one block for each console
that differs from the default settings.
For example:
CONSOLE=3
MIDWINBGCOLOR=NAVY
MIDWINTXTCOLOR=WHITE
CMDWINBGCOLOR=GREEN
CONSOLECALL=G8PZT-4
MMASK=1f ; AX25/Netrom only
MPORTS=1-2 ; Monitor ports 1 and 2 only
ENDCONSOLE
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(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(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(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(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(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(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 <keyword>=<value>,
each on a separate line. (If you do not understand the
significance of the <>, please see the conventions section).
Keywords are not case sensitive, and may be specified in any
order.
For example:
PORT=2
(directives here)
ENDPORT
Some directives are mandatory, but most are optional. The
full range of port keywords is summarised below:
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(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(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(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(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(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(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.