packet:xrouter:docs:section9-miscellaneoustopics
Table of Contents
Section 9 - Miscellaneous Topics
AD-HOC
AD-HOC(9) XROUTER REFERENCE MANUAL 26/9/2023
NAME
AD-HOC -- Ad-Hoc Networking.
DESCRIPTION
"Ad-hoc" networking (AHN) is a variant of AXUDP linking. It
differs from "normal" AXUDP in that the UDP/IP parameters of
the link partners are not specified in advance, and instead
of "one PORT per link", all AHN links share the same PORT.
As the partners' UDP/IP details are not known in advance, AHN
is "passive", i.e. like an AXTCP server, it must wait for
incoming connections. Thus AHN can only be used at ONE end of
a link.
Upon receipt of an incoming AXUDP packet, XRouter "remembers"
its UDP/IP parameters, and uses them to return the replies.
At present, the UDP/IP parameters are remembered for only ten
minutes, but as long as the AX25 T3 (link check) time is less
than that, the link check packets prevent the parameters
from expiry.
The "ODN" command currently lists the stored parameters.
AHN can be used at the same time as "normal" AXUDP, and they
can both share the same INTERFACE. But there must only be one
PORT devoted to AHN. If you try to specify more than one AHN
port, XRouter will refuse to start.
CONFIGURATION
An AHN PORT requires an AXUDP INTERFACE in XROUTER.CFG, for
example:
INTERFACE=9
TYPE=AXUDP
MTU=256
ENDINTERFACE
(Choose the interface number to suit yourself).
Only TYPE=AXUDP and MTU= are required, all other parameters
are ignored (at present).
The minimum configuration for an AHN PORT is as follows:
PORT=9
ID=Ad-Hoc Networking
INTERFACENUM=9
IPLINK=0.0.0.0
UDPLOCAL=10094
LEARN=1
ENDPORT
IPLINK has no default value. It must be a proper dotted-quad
IP address i.e."0.0.0.0", not "0". This "special" IP address
is what tells it to be an Ad Hoc Networking port.
UDPLOCAL is the UDP "port" number upon which XRouter listens
for incoming AHN packets. This MUST be different from any
UDP ports used by "normal" AXUDP. Don't forget to "port
forward" incoming UDP to this address.
Note that UDPREMOTE must not be used.
If there's an ETHERNET port available, XRouter will use its
own IP stack for AHN, otherwise it will use the Linux stack.
If you want to "force" the use of the Linux stack, for
example if the link partner is on the same machine, add the
following line to the PORT configuration:
IPADDRESS=127.0.0.1
Finally, LEARN tells XRouter to remember the IP address and
udp port of the peer.
CAVEATS
AHN allows unplanned and unregulated linking between nodes,
and is therefore deprecated. Unknown nodes which come and go
at random can distort the network and cause excessive network
management traffic. The facility was provided only because
there was a demand for it. It's just another tool in the
networking tool box.
It is assumed that the link partner receives AXUDP on the
same UDP port as it sends from. If this is not the case, AHN
will not work, and normal AXUDP must be used.
SEE ALSO
AXTCP(9) -- AX25 over TCP.
AXUDP(9) -- AX25 over UDP.
LEARN(7) -- Learn Unsolicited AX*P Peer Details.
XROUTER.CFG(8) -- Main Configuration File
APPLS
APPLS(9) XROUTER REFERENCE MANUAL 19/10/2023
NAME
APPLS -- Application Support.
DESCRIPTION
In this context, "applications" refers to programs which use
XRouter to provide their connectivity with the outside world.
Unlike its 16 bit forerunner, XRouter does not provide the
BPQ Host API, but it does provide the following means for
supporting applications:
- AGW TCPHOST Interface
- WA8DED Hostmode Emulation
- TNC2 Emulation
- KISS / SLIP / PPP
- Remote Host Protocol (RHP)
- Proxies
- TCP applications (e.g. QtTermTcp)
Defining Applications
~~~~~~~~~~~~~~~~~~~~~
Some applications, such as those using the TNC2 emulator, do
not accept incoming connections, and this section doesn't
apply to them. Nor does it apply to applications accessed
via KISS / SLIP / PPP or proxies. For the remainder,
read on...
In order for applications to be able to accept incoming
connections, they must be specified in XROUTER.CFG, using
APPL configuration blocks.
Each definition block must begin with APPL=<number> and must
end with ENDAPPL. There must be a separate block for each
application. Applications which use more than one stream
need only a single definition. The APPL block should contain
one or more of the following keywords:
APPLNAME The nickname or shortcut by which the application
is accessed from XRouter's command line. e.g.
"PMS". If a user types this name at the command
prompt, they will be connected to the application.
APPLCALL The AX25 layer 2 callsign which the application
will use. If specified, the application will accept
AX25 L2 connects to this callsign, subject to the
setting of APPLMASK (see below).
APPLALIAS The AX25 layer 2 "alias" used by the application.
If specified, the application will accept AX25 L2
connects to this callsign, subject to the setting
of APPLMASK (see below).
APPLQUAL Netrom quality to broadcast (0-255). If a non-zero
value is specified here, the APPLCALL will be
included in Net/Rom nodes broadcasts and the
application will be connectible at AX25 layer 4.
The higher the quality, the further the node entry
will propogate.
APPLFLAGS defaults to 0 if omitted. The flags are as follows:
Bit Value Action
------------------
0 1 Application has SYSOP privileges.
1 2 Allow "guest" users to access the appl.
2 4 XRouter sends "Connected to (applcall)"
to the user upon connection to an
application. This is not required if the
application sends its own "Connected to"
message.
3 8 XRouter sends "Connected to (usercall) to
the application when a user connects.
APPLTYPE is only required for TCP applications at present.
The format is APPLTYPE=TCP,[ip_addr:]tcp_port
(ip_addr is only required if the application is on
a different computer)
Most fields within an application definition block are
optional - you may have for instance choose to have an
APPLNAME but no APPLCALL, meaning the application could only
be reached by typing the applname at the command prompt.
Or you could have an APPLCALL but no APPLNAME, in which case
the application would be directly connectable, but wouldn't
be reachable from a command line shortcut.
The application number must be between 1 and 8. Some BPQHOST
applications have fixed application numbers, e.g. BBS's and
PMS's must usually be the first application and Host programs
such as PAC4 are usually the second. However, since BPQHOST
API isn't currently implemented, the choice of application
number is arbitrary at present.
Example for a Bulletin Board System application using WA8DED
hostmode. It is accessed by typing "BBS" at the command
prompt or by connecting via AX25 or NetRom to the callsign
GB7PZT or the alias PZTBBS:
APPL=3
APPLNAME=BBS
APPLCALL=GB7PZT
APPLALIAS=PZTBBS
APPLQUAL=100
APPLFLAGS=4
ENDAPPL
In the following example, the application has no callsigns or
quality, so it can only be reached by issuing the command
"HOST" at the command prompt:
APPL=2
APPLNAME=HOST
ENDAPPL
Example for incoming connections to a TCP application such as
QTTERMTCP. It can be acessed by an AX25L2 connection to G9ZZZ
or by typing "SYSOP" at the command prompt. QtTermTCP is set
up to listen on TCP port 8015:
APPL=1
APPLNAME=SYSOP
APPLTYPE=TCP,8015
APPLCALL=G9ZZZ
ENDAPPL
AX25 Visibility
~~~~~~~~~~~~~~~
If you want an application to be directly connectible on a
particular port, the application must have an APPLCALL, an
APPLALIAS or both, and the corresponding bit in that port's
APPLMASK must be set.
APPLMASK specifies which applications will be directly
connectible on a given port. The default is 255, which
allows all applications. The value is made up by adding
together the desired selection from the following numbers:
1 - Enable Application 1
2 - Enable Application 2
4 - Enable Application 3
8 - Enable Application 4
16 - Enable Application 5
32 - Enable Application 6
64 - Enable Application 7
128 - Enable Application 8
For example, if a port's definition contains "APPLMASK=9", it
will only allow direct connections to applications 1 and 4 on
that port, providing those applications have either an
APPLCALL or an APPLALIAS.
Downlinking From Applications
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Certain settings of a port's CFLAGS may prevent all
downlinking on that port. For example, in a mixed CB/HAM
node you may need to use CFLAGS=1 to prevent CB users from
making L2 downlinks on the HAM port. But that would also
prevent HAM applications from downlinking on that port.
This can be solved by setting bit 2 (decimal value 4) of
CFLAGS, which allows applications to downlink
unconditionally.
Setting this flag allows applications to make L2 downlinks on
ports which are closed to users, e.g. CFLAGS=1 prevents
everyone excepts sysops from downlinking, whereas CFLAGS=5
prevents everyon except sysops and applications from
downlinking. See CFLAGS for more details.
SEE ALSO
AGWHOST(6) -- AGW Application Support.
CFLAGS(7) -- Connection Control Flags.
DEDHOST(9) -- WA8DED Hostmode Emulator.
RHP(9) -- Remote Host Protocol.
TNC2(9) -- TNC2 Emulator.
XROUTER.CFG(8) -- Main Configuration File.
APRS
APRS(9) XROUTER REFERENCE MANUAL 21/10/2023
NAME
APRS -- Automatic Packet Reporting System.
DESCRIPTION
APRS is (currently) an acronym for "Automatic Packet
Reporting System", although the name tends to change from
time to time! (it was originally called "Automatic *Position*
Reporting System, and there has been talk of re-branding it
to Automatic PRESENCE Reporting System).
It is a protocol that uses AX25 UI frames and digipeaters to
report a wide variety of parameters such as position, speed,
weather, bearing, status, objects, frequencies and so on.
XRouter includes the following sub-systems that support or
make use of APRS:
- APRS Generic Digipeating
- APRS Igate
- APRS Server
- APRS Messaging Shell
- APRS Weather reports
- APRS DX recording
- APRS Queries
- Positions, distances & directions in MH lists
Generic digipeating is a complex type of digipeating which
responds to special digipeater addresses, and modifies a
packet's digipeater addresses in transit. It also prevents
duplicates and looping.
The Igate is a client daemon that allows APRS data to flow to
and from between the Internet APRS system and RF ports,
messaging shell etc.
The APRS server allows APRS applications such as UI-view to
use XRouter to access all the APRS data handled by XRouter.
The APRS messaging shell allows users to send and receive
APRS messages and bulletins.
Weather reports are received via RF and/or Igate, and are
made available for users to read using the WX command.
The DX feature stores a list of the furthest stations heard
via RF.
APRS Queries allow RF users to query which nodes are on
channel, what DX they heard, what messages are waiting etc.
MHeard lists are able to display the positions, bearings and
distances of stations that broadcast APRS data.
Specifying XRouter's Position
~~~~~~~~~~~~~~~~~~~~~~~~~~
In order for most of these systems to work, XRouter needs to
know its position on the globe. There are currently three
ways to achieve this...
The easiest method is to use the "LOCATOR=" directive in
XROUTER.CFG, which enables you to specify an approximate
location at the centre of a 1Km "Maidenhead" locator square,
e.g. "LOCATOR=IO82VJ".
If you don't know your LOCATOR square, an alternative method
is to use lATITUDE and LONGITUDE directives in XROUTER.CFG.
These are specified in decimal degrees, which can easily be
found from Google Maps. East and North are positive numbers,
while South and West are specified as negative numbers. You
should not append N S E or W.
Another method, which allows more precise (or less precise
if you prefer) positioning, is to include an APRS-style
position in IDTEXT, starting within the first 40 characters.
The format is "!ddmm.mmN/dddmm.mmE#" where dd represents
degrees of latitude/longitude and mm.mm represents minutes
to two decimal places. "N" and "E" may be replaced by "S"
and "W" as appropriate. For example:
IDTEXT
!5224.00N/00215.00W# Kidderminster Router (KDRMIN)
***
You are urged to use at least one of these methods to define
XRouter's position. It really does make Packet more
interesting!
APRS Generic Digipeating
~~~~~~~~~~~~~~~~~~~~~~~~
XRouter supports APRS generic digipeating for RELAY, WIDE,
TRACE, TRACEn-N and WIDEn-N aliases.
Generic digipeating is configured on a port by port basis,
using the flags marked "*" in "DIGIFLAG" as follows:
1 Digipeat UI frames (note 1)
2 Digipeat non-UI frames (note 1)
*4 Enable RELAY generic digipeating.
*8 Enable TRACE generic digipeating.
*16 Enable WIDE (Well sited stations only!)
*32 Allow APRS 3rd party digi via L4.
*64 Allow digipeating to Internet (IGate).
*128 Allow digipeating from Internet (IGate).
*256 Enable UITRACE digipeating
*512 Enable UIFLOOD digipeating
Add the appropriate numbers together to enable the
desired combination of services.
Note 1: Irrespective of the generic digipeater settings, you
may choose to allow regular digipeating (i.e. using XRouter's
normal callsign or alias) on APRS ports, allow regular
UI-only digipeating, or disable regular digipeating
altogether, by manipulating bits 0 and 1 of DIGIFLAG.
SSID Substitution Digipeating
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
UITRACE and UIFLOOD represent two special addresses that are
suffixed with pseudo-SSID's, e.g. "TRACE4-4" and "WIDE2-2".
These addresses can digipeat several times. The first digit
specifies the maximum number of hops, and the second is the
hop counter, which is decremented each time the frame is
digipeated.
These two addresses behave slightly differently however. When
a frame is digipeated on the alias specified by UITRACE, each
digipeater inserts its own callsign in the digipeater list,
and decrements the "SSID". Frames digipeated on the UIFLOOD
address have their SSIDs decremented, but the digi doesn't
insert its own callsign.
For the sake of consistency with UI-View, UITRACE defaults to
"TRACE", giving TRACEn-n digipeating, and UIFLOOD defaults to
WIDE, giving WIDEn-n digipeating.
New-N Paradigm
~~~~~~~~~~~~~~
According to the APRS "New-N Paradigm", RELAY, TRACE and WIDE
are deprecated, UITRACE should be set to "WIDE", and UIFLOOD
should be set to a "state" code (e.g. "GBR" for the UK).
One of the main reasons for the New-N Paradigm was the fact
that some of the older digipeaters would digipeat the same
packets over and over. This does not happen with XRouter.
Not everyone agrees with the "New-N Paradigm, so the choice
of which features to enable is left you you.
Mixing Modes
~~~~~~~~~~~~
In quiet areas, you may wish to mix APRS and normal
connected-mode operations on the same port, and that is the
default if you enable any of the above flags in DIGIFLAG.
However, in most areas, APRS tends to be on a separate
frequency reserved for "unconnected nets", and you may wish
to prevent people from connecting to the node or downlinking
from it on your APRS-only ports.
The CFLAGS keyword can be used in the PORT section of the
XROUTER.CFG file to control uplinking and downlinking as
follows:
0 Prevent uplinking and downlinking.
1 allow uplinking only.
2 allow downlinking only.
3 allow both up and downlinking.
ID Beacons
~~~~~~~~~~
Whilst all sysops are urged to include an APRS position in
their normal IDTEXT, a dedicated APRS port may require a more
detailed and cryptic ID beacon, therefore you may define a
different IDTEXT for each port if necessary.
A "regular" port would include a position followed by some
human-readable text, whereas the APRS-only ports would
include additional data such as power / height / gain /
direction, wind speed, bowel movements etc., in encoded
format.
The IDTEXT may be sent via digipeaters by including the
IDPATH keyword in the relevant port configuration section of
XROUTER.CFG.
Dupe Suppression
~~~~~~~~~~~~~~~~
XRouter checks for its own callsign or alias in previously
used digipeaters to prevent digi looping. It will not
digipeat frames it originated, and will not digipeat the
same frame within 9 seconds.
DX Facility
~~~~~~~~~~~
The "DX [port]" command shows the best received APRS DX. It
only works if XRouter's position has been defined as
described earlier.
The DXFLAGS keyword in the .CFG file controls whether or not
the DX list contains callsigns heard via digipeaters.
The DX list may be queried by RF stations, by means of APRS
queries.
APRS / UI-View queries
~~~~~~~~~~~~~~~~~~~~~~
XRouter responds to the following general queries:
?APRS? All stations query.
~\xFD~ UI-View general query.
?IGATE? Igate query.
The response to the first two is the ID beacon for the port,
which should contain the APRS position and station type. The
response to the ?IGATE? query shows the message and local
user counts.
The following "directed" queries (directed at portcall) are
supported:
?APRSD Directly heard stations list.
Responds with a list of stations heard directly
on the receiving port (i.e. not via digipeaters
or via 3rd party networks)
?APRSM Un-delivered messages query.
If there are any un-delivered or expired
messages addressed to the sender of the query,
they are re-activated and transmitted on the
port which received the query.
?APRSP Station Position.
If the sysop has defined XRouter's position, it
is sent in response to this query.
?APRSS Station status.
The response consists of the software type and
version plus a list of the enabled generic
digipeater calls.
?PING?
?APRST Trace Route.
Both of these return the route by which the
query was received.
~\xFE~n UI-View "ping".
The response to this query is a UI-View ack for
the ping id.
~\FC~n UI-View "DX" query.
Responds with a UI-View ack, followed by details
of the best DX heard directly by XRouter
(digipeated packets are NOT included!)
See www.aprs.org for more info about APRS.
SEE ALSO
AMSG(1) -- APRS Messaging Mode.
APRS-SRV(9) -- APRS Server.
APRS-SVC(9) -- NetRomX APRS Service.
DX(1) -- Display Distant APRS stations.
IGATE(9) -- APRS Igate.
MHEARD(1) -- Display Recently Heard Stations.
MHEARD(9) -- About the MHeard Facility.
WX(1) -- Display APRS Weather Information.
XROUTER.CFG(8) -- Main Configuration File.
APRS-SRV
APRS-SRV(9) XROUTER REFERENCE MANUAL 21/10/2023
NAME
APRS-SRV -- APRS Server.
DESCRIPTION
XRouter includes a rudimentary APRS server, which enables
suitable APRS clients, such as UI-View, to connect to it on
the LAN and exchange APRS traffic. The number of concurrent
clients is not limited.
The server is available via NetRomX service 14, and TCP/IP.
TCP Port Number
~~~~~~~~~~~~~~~
The server listens for incoming connections on TCP port 1448.
There is a tradition of choosing port numbers for APRS
servers which represent the frequencies used by APRS, hence
port 1448 was chosen because XRouter originates in the UK,
and many European countries use 144.800 MHz.
Overview Of Server
~~~~~~~~~~~~~~~~~~
The following APRS packets are sent to clients:
- APRS traffic received by any of XRouter's radio ports.
- Traffic sent by other clients.
- Traffic sent by users of XRouter's APRS messaging shell.
- Filtered traffic from Internet APRS servers (if
XRouter's IGATE is connected to an Internet APRS server)
APRS packets from clients are distributed as follows:
- To other clients, excluding the sender.
- To XRouter's APRS messaging shell.
- To radio ports (only if client is fully registered)
- To Internet APRS servers via IGATE (if IGATE enabled).
Registration and Login
~~~~~~~~~~~~~~~~~~~~~~
Registration of clients is necessary to prevent unauthorised
use of radio frequencies by unlicensed people.
This may seem overly restrictive if your system is only used
on a private LAN, but if you are connected to the Internet,
it is essential.
For example, if an unlicensed user connects to your server
via the Internet, he must be prevented from sending traffic
to your local RF ports. He must also be prevented from
sending traffic via your IGATE (if it is enabled) into the
Internet system, and thence to other people's RF ports.
Therefore, clients are required to complete a log-in process
before they are allowed to send any traffic. Log-in is not
required for receive-only operations.
The server accepts two different types of login. When a
user registers an APRS client program such as UI-View, he
receives a "validation number" which XRouter uses in
combination with the callsign to verify the user. Verified
users may send traffic to local RF ports, or if IGATE is
active, via other IGATES.
If the user has NOT registered his copy of UI-View, the
default validation number of "-1" allows him to send traffic
to other clients and to the Internet, but that traffic will
not be gated locally to RF, and is marked in such a way that
it will not be gated to RF by other IGATES. This allows
unregistered clients to communicate with each other via the
Internet, but not via RF. The client may only send APRS
packets whose source callsign matches the login callsign.
The alternative login system allows clients to verify
themselves by supplying their callsign and a password which
has been agreed with the sysop. The password replaces the
validation number in a login string.
The login string is the only "command" accepted by the APRS
server, and must take the form:
"user <callsign> pass <password>"
where <password> could be either a validation number or a
text string, for example, "user g8pzt pass beanzmeanzheinz",
or "user g7zzz pass 32751". Login is not acknowledged.
The Client Connection
~~~~~~~~~~~~~~~~~~~~~
There is no time-out on client connections, therefore there
is no need for the client to send "keep-alive" signals.
If the client connection is too slow to cope with the
incoming data rate, packets to the client may be discarded.
Local <> Internet Server Gating
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If IGATE is not running, no packets are gated to or from the
Internet.
Packets received from the Internet are not gated to clients
unless they satisfy the IFILTER (Internet Filter) filtering
rules in IGATE.CFG. Likewise, packets received from clients
are not gated to the Internet unless they satisfy the
PFILTER (Packet Filter) rules.
The following traffic is NOT gated from RF to Internet
- Packets in "third party" format.
- Packets which do not include the network identifier
"TCPIP" in the digi path.
- Packets which include the dummy callsigns NOGATE or
RFONLY in the digi path.
Using UI-View as a Client
~~~~~~~~~~~~~~~~~~~~~~~~~
Select Setup/APRS Server Setup.
In the box marked "Select A Server", enter the hostname and
TCP port number of XRouter's APRS server, e.g.
"myserver:1448" or "192.168.0.2:1448". If the client is on
the same computer as XRouter, use "localhost:1448" or
"127.0.0.1:1448". (If you use a private hostname, you may
need to add a suitable entry into the HOSTS file in the
WINDOWS directory, or Linux equivalent.)
Check the boxes marked "Open the gateway" and "Gate local
messages".
If you have a registered version of UI-View, check the box
marked "APRServe log on required", and enter your validation
number.
If your copy of UI-View is unregistered, you will be able to
log on to XRouter's APRS server with the default validation
number of -1, but your packets will not be gated to RF.
To obtain full privileges using an unregistered copy, you
must have a password, which must be registered with your
callsign in XRouter's USERPASS.SYS file. The callsign must
not include the SSID, e.g. if UI-View's callsign is
"G8PZT-11", the entry in USERPASS.SYS should simply be
"G8PZT". Un-check the "APRServe log on required" box, and
in the box marked "Text to send upon connection" enter
UI-View's callsign (with SSID) and your password in the
following form:
user g8pzt-11 pass virago
SEE ALSO
APRS(9) -- APRS in XRouter.
APRS-SVC(9) -- NetRomX APRS Service.
APRSPORT(7) -- TCP Port for APRS Server.
IGATE(9) -- APRS-Internet Gateway.
IGATE.CFG(8) -- Igate Configuration File.
TCP-PORTS(6) -- TCP Service Ports.
USERPASS.SYS(8) -- User Passwords File.
XROUTER.CFG(8) -- Main Configuration File.
APRS-SVC
APRS-SVC(9) XROUTER REFERENCE MANUAL 22/9/2023
NAME
APRS-SVC -- NetRomX APRS Service.
DESCRIPTION
NetRomX standard service 14 is an "APRS server". This relays
APRS packets in the following way:
The server sends the following APRS packets to clients:
- Traffic received by any of XRouter's radio ports.
- Traffic sent by other clients of the server.
- Traffic sent by users of XRouter's APRS msg shell.
- Filtered traffic from Internet APRS servers (if
XROUTER's IGATE is connected to such a server)
APRS packets from clients to server are distributed as
follows:
- To other clients, excluding the sender.
- To XRouter's APRS messaging shell.
- To radio ports
- To Internet APRS servers via IGATE (if IGATE is running).
Traffic is in plain ASCII text, with lines delimited by
Carriage Return (CR) (ASCII 13). For example:
MB7UYL>APXR01:=5224.00N/00215.00Wn Kidderminster, Worc's
{Xrouter 501y}
VE2PKT-4>ID:!4625.96N/07237.66WB 147.435Mhz 1.2Kb, VE2PKT-4,
XRPI Router
VK2DOT-1>ID:!3323.21S/15121.42E# Niagara Park Node -
(VK2DOT-1) 44.136.16.1
No login is required, and no commands are accepted. Simply
disconnect when you are finished.
SEE ALSO
APRS(9) -- APRS in XRouter.
APRS-SRV(9) -- APRS Server.
IGATE(9) -- APRS-Internet Gateway.
SERVICES(9) -- NetRomX Standard Services.
APRS-SVC(9) END OF DOCUMENT
ARP
ARP(9) XROUTER REFERENCE MANUAL 21/10/2023
NAME
ARP -- Address Resolution Protocol
DESCRIPTION
The Address Resolution Protocol handles the association
between IP addresses and "hardware" (Ethernet or AX25)
addresses.
In order for IP datagrams to be handled by AX25 or Ethernet
links, they must first be "wrapped" in AX25 or Ethernet
packets.
The destination addresses of these packets is determined by
the process of "Address Resolution".
For example, imagine that you want to send an IP datagram to
one of your neighbour nodes via RF. TNC's don't understand
IP, so you can't simply transmit a raw IP datagram onto the
airwaves. Your node must first "wrap" the datagram in an
AX25 frame addressed to the neighbour node. Upon receipt by
the neighbour, the frame is "unwrapped", and the IP datagram
contained therein is handled by the IP router.
Exactly the same process is required to send IP over
Ethernet, except that Ethernet frames are used instead.
The destination address is usually obtained from an "ARP
Table", that stores each neighbour's IP addresses along with
their AX25 or Ethernet address. This table can be built
manually using ARP commands, or dynamically. A typical ARP
table would contain entries similar to this:
IP Address Type Hardware addr
------------------------------------------
44.131.91.2 AX25 G8PZT
44.131.90.6 AX25 G8JVM-5
192.168.0.23 Ether 00:12:34:66:21:DA
If the destination address is not in the ARP table, XRouter
broadcasts an "ARP request" packet, asking if anyone knows
the hardware address associated with the destination IP
address. The destination node replies with an "ARP reply",
giving the AX25 address that the datagram should be
addressed to. XRouter adds this data to the ARP table, then
uses it to wrap and send the datagram.
The "ARP entries" in the table usally have a finite lifetime
(usually 15 minutes), because neighbours sometimes change
their hardware addresses. This lifetime may be altered by
the sysop.
When an entry gets too old, it is purged from the table,
forcing XRouter to send another ARP request, thus picking up
the new hardware address. The sysop may override this by
"locking-in" ARP entries.
A router other than the destination may reply to an ARP
request if it is the gateway to a "hidden" network containing
the destination. This is called "proxy ARP", is implemented
in XRouter and is detailed in RFC1027.
The ARP protocol is detailed in RFC826.
SEE ALSO:
ARP(1) -- ARP Commands.
AUDIO
AUDIO(9) XROUTER REFERENCE MANUAL 2/9/2023
NAME
AUDIO -- Audio Output.
DESCRIPTION
Raspberry Pi's and modern laptops do not have the traditional
"PC speaker", so they cannot play the usual console bells and
alerts. However, a sound device can be used instead.
To enable sounds (assuming a suitable sound device is
present), put the following directive anywhere in XROUTER.CFG
# Audio device for sound output:
# Default OSS device is /dev/dsp (/dev/audio on Rasp pi)
#
AUDIODEVICE=/dev/dsp
#
This uses OSS, (a) because OSS has been found to work much
better than ALSA, and (b) because ALSA requires the host
machine to have the "libasound" library installed. The
XRouter philosophy is to avoid dependencies where possible.
Having said that, XRouter can be supplied in "with-ALSA"
versions if required.
In order to use sound, on some platforms you may need to
first run the command:
sudo modprobe snd-pcm-oss
The command only needs to be run once. Thereafter XRouter
can be started and stopped without needing to use it again.
On some platforms the modprobe command is not needed at all,
but Linux has been gradually phasing out OSS, making it ever
more awkward to use.
You could add "snd-pcm-oss" into the /etc/modules file, which
causes it to load the module at bootup.
If snd-pcm-oss is not found on the system, and cannot be
installed from a repository, one method which has been found
to be successful is to run XRouter from within an OSS
"wrapper" program such as "aoss" like this:
"aoss /home/pi/xrouter/xrpi"
CAVEATS
The downside of OSS is that it won't share the audio device,
so if you have XRouter's audio enabled but another app is
already using the sound device, XRouter will fail at boot.
SEE ALSO
AUDIODEVICE(7) -- Specify Audio Device
BELL(1) -- Console sounds control
XROUTER.CFG(8) -- Main Configuration File.
AUTOQUAL
AUTOQUAL(9) XROUTER REFERENCE MANUAL 19/10/2023
NAME
AUTOQUAL -- Automatic Route Quality.
DESCRIPTION
Automatic Route Quality Measurement" (Autoqual) is an optional
tool to help sysops set consistent and meaningful NetRom route
qualities.
Background
~~~~~~~~~~
NetRom makes routing decisions based on a fairly arbitrary
metric, i.e. the "route quality", which is assigned by sysops,
and disseminated in nodes broadcasts.
In the better-managed parts of the NetRom network, route
qualities tend to be assigned according to the baud rate of
the link, with adjustments for retry rates, duplex / simplex
and shared channels.
However, there is no standard methodology for assigning
quality, so not only will each sysop's notion of quality
differ from that of other sysops, but also he will probably
incorrectly assign the relative qualities of his own links.
This leads to inconsistency and distorted routing.
In other parts of the network, route qualities are simply
assigned to 192 regardless of how good or bad the link is.
This also leads to inconsistency and less-than-optimal
routing decisions.
The actual "goodness" of a link may continually change with
atmospheric conditions, data throughput, other channel
activity, QRM etc. At certain times of day for example, it
may be better to use an alternative link.
A more accurate notion of "goodness" is simply the "Round
Trip Time" (RTT) for the link, i.e. the time taken to send a
packet and get a reply. After all, this is what *really*
matters to users. A link which responds quickly (i.e. with a
low RTT) is perceived by users to be better than a link which
responds slowly. The RTT will track changes in retry rate,
channel loading etc.
The RTT can be easily and consistently measured by software
on a continuous basis, thus the "goodness" of the link is
accurately known at all times, and all routers of the same
type will give comparable values independently of the sysop's
notions of quality.
Implementation
~~~~~~~~~~~~~~
XRouter continually measures the RTT of neighbour links and
uses the smoothed value to calculate a notional "route
quality" every 5 minutes. The maximum, minimum and standard
deviation of this quality are calculated and recorded for
later display, and the value is further smoothed.
The smoothed calculated quality is displayed by the "R Q"
command, and can either be used as a guide to allow the sysop
to fix the RQ at a sensible value, or if the route has been
configured for it, XRouter can use it dynamically, by setting
the route's quality to the calculated value.
This RTT to quality conversion is tailored to the British
notion of quality, which gives somewhat lower but more
meaningful qualities than used elsewhere. For example, a
typical 1200 baud half-duplex link with low retry rate would
produce a calculated quality around 120. A good 9600 baud half
duplex link would equate to around 190, with 210 for a really
good full duplex 9k6 link.
RTT measurement primarily uses L3RTT frames, but in their
absence it also uses measurements of traffic throughput and
retry rate.
Enabling Automatic Route Quality
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Route quality calculation is automatic and continuous.
However the calculated value is not actually used without the
sysop's consent.
In order to allow the route quality to be automatically
adjusted, the sysop must specify a RQ between 256 and 511
when adding a route using the "ROUTE ADD" command.
Alternatively, setting the PORT quality between 256 and 511
will cause all *new* routes (not locked in ones) learned on
that port to use automatic quality.
A quality between 256 and 511 will instruct XRouter to use
"automatic" quality, with an initial value of (qual-256).
SEE ALSO
ROUTES(1) -- Add, Drop and List NetRom Routes.
QUALITY(7) -- Default NetRom Quality.
AXIP
AXIP(9) XROUTER REFERENCE MANUAL 21/10/2023
NAME
AXIP -- AX25-over-IP Tunnelling.
DESCRIPTION
AXIP is AX25 "encapsulated" within IP datagrams. This
enables AX25 systems to communicate with each other via
TCP/IP networks (e.g. the Internet). The frame structure is
as follows :
.-----------.------------------------.-----.
| IP header | AX25 frame | CRC |
'-----------'------------------------'-----'
(20 bytes) (Typically 15-340 bytes) 2 bytes
The AX25 links created using AXIP can in turn support NetRom
and amateur TCP/IP, just like real radio links.
Setting Up AXIP Links
~~~~~~~~~~~~~~~~~~~~~~
Assuming you have a prospective AXIP partner, you would set
up an AXIP link as follows:
1) Configure and test IP routing between you and your
partner. If you don't have reliable IP routing there's no
point in proceeding!
If you are linking via the Internet, it makes sense to
use the Internet IP addresses for this purpose, rather
than the amateur (44.x.x.x) ones, because the routing is
more reliable and the throughput is faster.
2) If your partner has a dynamic IP address, they must have
an account with a "dynamic DNS" provider, and you must
use the hostname thus provided for all operations. If
you use the IP address instead, the link will stop
working when the address changes.
3) If you wish to use your prospective partner's hostname
(e.g. "g8pzt.ath.cx") instead of their IP address, your
system needs access to a Domain Name Server (DNS). This
would usually be provided by Linux nowadays, so you may
remove all "DNS=" lines from XROUTER.CFG.
4) If using the partner's hostname, verify that
"PING <hostname>" resolves the address correctly.
5) Add an AXIP interface to XROUTER.CFG as follows:
INTERFACE=7
TYPE=AXIP
MTU=256
ENDINTERFACE
(Choose the interface number to suit yourself).
This interface can support an unlimited number of AXIP
PORTs. You may define multiple interfaces if your ports
need different MTU's.
Only TYPE=AXIP and MTU= are required, all other
parameters are ignored (at present).
6) For each AXIP partner, add a PORT similar to this:
PORT=8
ID=AXIP link with WA3IP
INTERFACENUM=7 <-- Points to INTERFACE above
IPLINK=55.73.88.69
FRACK=2000
RESPTIME=200
ENDPORT
You must specify at least ID, INTERFACENUM, and IPLINK.
IPLINK is the remote host's IP address or hostname. It is
more efficient to use IP addresses, if you are able to do
so, because it removes the need to resolve the hostnames,
but see (2) above. The assigned "protocol number" for
AXIP is 93 (decimal).
MAC parameters such as TXDELAY, TXTAIL, FULLDUP, PERSIST,
SLOTTIME, SOFTDCD etc. are meaningless for AXIP, but
FRACK, RESPTIME, PACLEN, MAXFRAME, QUALITY etc. operate
as normal.
On fast internet links you may wish to use a much lower
FRACK, say 2000ms, than on radio. It is not recommended
that you reduce it much below 1000ms, as it needs to be
*at least* twice the worst round-trip time plus the other
end's RESPTIME.
RESPTIME is probably the one which will have most effect
on the responsiveness of the AX25 link, because it
controls the time delay between receiving a packet and
sending an ACK. It should be just a little more than the
time it takes to receive a maximum length packet. For
example, at a data rate of 56Kbits/sec, a 256 byte packet
lasts less than 50msec, so RESPTIME=50 would be adequate.
However the timing jitter due to operating under Windows
means that RESPTIME should be more like 200ms.
7) If XRouter is indirectly connected to the Internet via an
intermediate router, that router will probably be using
some form of NAT (Network Address Translation) to share
one "public" IP address between several systems on your
LAN. The "front end" router will probably route outgoing
AXIP without problem, but it will not know where to send
incoming AXIP unless explicitly configured.
Configuring such a router for AXIP usually involves
specifying a protocol number (93 for AXIP), and the LAN
IP address of a machine to which it should be routed,
i.e. XRouter's LAN IP address.
You are advised that not all domestic routers can be
configured to route incoming AXIP as it is not a
commercially recognised protocol. Some routers only
allow TCP and UDP port redirection, with no provision for
any other protocol. If you or your link partner have
such a router, you may need to consider AXUDP instead -
see later.
8) Your link partner must set up a reciprocal arrangement,
i.e. their IPREMOTE must be set to your public IP address
or hostname.
If everything has been set up correctly, you should be able
to connect with your new neighbour node immediately, at least
at AX25 layer 2. You can test this by entering the command
"C n ALIAS-1", where n is the PORT number of your link, and
ALIAS is the node alias of your link partner. If this doesn't
work, you or your partner have made a mistake somewhere in
the configuration.
Even if everything is configured correctly, it may take a
while for NetRom to configure itself for the new link, as the
nodes need to exchange NODES broadcasts first. Once they
have done so, there should be no delays in future.
Notes
~~~~~
You may of course use AXIP to communicate between nodes on
the LAN, as long as they are not on the same machine.
If you have more than one node on your LAN using AXIP, your
Internet router is only able to direct incoming AXIP to *one*
of them. This means you can only have one AXIP node per
public IP address.
DO NOT set up an AXIP link to a link partner if you already
have an AXUDP link. This is a common mistake, and is likely
to cause problems!
Using one port per neighbour may seem wasteful, but it is a
reliable method, and it allows you to monitor exactly what is
going on.
IP Routing Over AXIP
~~~~~~~~~~~~~~~~~~~~
As mentioned earlier, you may route amateur IP (44.x.x.x) over
your new AXIP link, and are encouraged to do so. Whilst the
amprnet purists will argue that this is not as efficient as
IP-over-IP (since it uses a few more bytes), it is a LOT
easier to set up, and doesn't require that your domestic
router and operating system can route IP-over-IP (many
routers are not able to route incoming IP-over-IP to a
specific PC, and Windows' IP stack totally blocks IP-over-IP).
To route amateur IP over an AXIP link, simply add an IP route
entry directing the required subnet to your neighbour's IP
address on the AXIP port using datagram mode. For example, if
the AXIP port is port 8, and the link partner (44.136.20.2)
is able to accept all amprnet traffic for Australia, the
entry would look like this:
IP ROUTE ADD 44.136.0.0/16 44.136.20.2 8 d
The source IP address for this mode of routing is the
IPADDRESS of the AXIP port. Therefore, if XRouter's main
IPADDRESS (in XROUTER.CFG) is not a 44-net address, you must
override it with a 44-net address on the AXIP port. If the
main IPADDRESS is a 44-net address, which is the recommended
configuration, do not specify IPADDRESS in the PORT
configuration block.
SEE ALSO
AXUDP(9) -- AX25-over-UDP Encapsulation
IP(1) -- IP Routing / Configuration Commands.
IPENCAP(9) -- IP-in-IP Encapsulation.
IPLINK(1) -- Display / Set a Port's IPLINK.
IPLINK(7) -- Peer Address of a Link.
IP-PRIMER(9) -- IP Addressing / Routing Primer.
IPROUTE.SYS(8) -- IP Routing / Configuration File.
XROUTER.CFG(8) -- Main Configuration File
AXSCTRL
AXSCTRL(9) XROUTER REFERENCE MANUAL 19/10/2023
NAME
AXSCTRL -- TCP/IP Access Control.
SYNOPSIS
This file deals with "access control", and is mainly of
concern if your system is directly connected to a non-amateur
TCP/IP network such as the Internet.
DESCRIPTION
Some of the users who access your system via the Internet may
be genuine Radio Amateurs, who may legitimately downlink on
radio frequencies, while other users may not. And different
countries may have different rules governing the
inter-connection of radio and non-radio networks.
Therefore some form of configurable access control is
required, and this is provided by the entries in ACCESS.SYS,
which specify the login requirements according to the
caller's IP address. For example you may specify that hosts
on your private LAN require no password.
If ACCESS.SYS is not present, the default action is for logins
to require a valid callsign only.
The entries in ACCESS.SYS allow various levels of access
control, e.g. username only, valid amateur radio callsign
only, username plus password, and valid callsign plus
password. They may also be configured for "guest access".
This is intended to let people look around, but not to do
anything that would cause a transmission to be made.
Guests are prevented from using the SEND, CHAT and CONNECT
commands, and from sending APRS messages using the APRS
messaging shell. For the TELNET command they are restricted
by the rules in the file TELGUEST.ACL. If that file is not
present, guests are denied access to the TELNET command.
Guests are not necessarily unlicenced people. They may simply
be hams who don't yet have a password for your system.
If an entry in ACCESS.SYS specifies that a login password is
required, the password should be located in file USERPASS.SYS.
Failure to meet the access requirements results in immediate
disconnection of the caller.
Sysop access using the "@" command, RLOGIN (tcp port 513) and
FTP do not use USERPASS.SYS, and are all controlled instead
by entries in the sysop password file, PASSWORD.SYS.
The "@" command, which is normally performed on publicly
visible radio links, uses the password to send a grid of
numbers, from which the caller must select one line and send
the matching characters from the password.
FTP uses the password grid method, but can be configured to
use use plain password (secure wired links only) if SYSOP=1
has been included in the appropriate PORT configuration in
XROUTER.CFG.
RLOGIN must only be used on secure wired networks because the
caller must send the password itself.
Access to the APRS server is normally controlled by the
"Validation number" which the user obtains from the author of
his APRS client program upon registration. However, if the
user has not registered his client, he may be granted access
to the server by including his callsign and a password in
USERPASS.SYS.
The Telnet Proxy and AGWHOST servers also use passwords in
USERPASS.SYS.
For further information you are referred to the sections
detailing the ACCESS.SYS, PASSWORD.SYS and USERPASS.SYS
files.
SEE ALSO
ACCESS.SYS(8) -- Telnet Access Control File.
APRS-SRV(9) -- APRS Server.
IDS(9) -- Intrusion Detection System.
PASSWORD.SYS(8) -- Sysop Password File.
USERPASS.SYS(8) -- User Passwords File.
XROUTER.CFG(8) -- Main Configuration File.
AXTCP
AXTCP(9) XROUTER REFERENCE MANUAL 29/9/2023
NAME
AXTCP -- AX25-over-TCP Tunnelling.
DESCRIPTION
AXTCP is AX25 "encapsulated" within a TCP stream. This
enables AX25 systems to communicate with each other via TCP/IP
networks (e.g. the Internet) in a similar way to AXIP and
AXUDP. The frame structure is as follows:
.-----.--------.---------.--------------------.-----.
| Len | IP hdr | TCP hdr | AX25 frame | CRC |
'-----'--------'---------'--------------------'-----'
Bytes: 2 20 20 Typically 15-340 2
(Len = (framelength-2), CRC = Cyclic Redundancy Check)
AXTCP is particularly useful when it isn't possible to route
AXIP or AXUDP, as detailed below:
The Problem
~~~~~~~~~~~
Many people in the UK use mobile broadband "dongles" to
provide their Internet connection, either because it's a lower
cost option than fixed-line broadband, or because the latter
is not available in their area, or because they're "roving".
As an example of the latter, a "mobile" node may be
established in a vehicle and used to provide a local packet
"hot-spot" for special events, emergency datacomms etc. It may
be using mobile broadband, WiFi or other available Internet
connections, and it is highly unlikely that such a connection
could be configured to route AXIP or AXUDP.
The characteristics of mobile Internet which prevent the use
of AXIP or AXUDP are that (a) the subscriber's IP address is
volatile (so you can't set IPLINK), and (b) the subscriber is
on a private network behind a NAT firewall, which doesn't pass
incoming AXIP or AXUDP traffic!
The solution
~~~~~~~~~~~~
AXTCP offers a solution to these problems. It differs from
AXIP and AXUDP in three respects:
- Firstly, it uses a bidirectional stream protocol (TCP/IP)
which guarantees that the packets can flow in both
directions, even through several stages of NAT and
firewalling.
- Secondly, it uses a client-server approach where the fixed
server has no need to know the mobile client's IP address
and port number. The connection is initiated by the client,
and the server simply responds via that connection.
- And thirdly, the TCP protocol ensures that no AX25 packets
are lost.
The AX25 links created using AXTCP can in turn support NetRom
and amateur TCP/IP, just like real radio links.
To use AXTCP, the "static" node is configured as an AXTCP
server, and the "mobile" node as an AXTCP client.
Configuring XRouter for AXTCP
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
AXTCP is enabled by declaring an INTERFACE with TYPE=AXTCP. A
single PORT is then attached to that interface.
AXTCP interfaces can act as server, client, or both at once,
depending on which keywords are included.
An AXTCP server can support several simultaneous client
connections, and a client can connect to several servers
simultaneously.
Note: When configuring a server, you must ensure that incoming
TCP/IP connections are directed to the server's TCP port, i.e.
there must be suitable NAT entries or "port forwarding" set
up in the Internet "front end" router.
Example AXTCP Server Interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following configures an AXTCP server, listening for
clients on TCP port 9393:
INTERFACE=5 <-- change to suit yourself
TYPE=AXTCP
MTU=256
INTNUM=9393 <- Server port
ENDINTERFACE
The INTNUM parameter activates the server and specifies the
TCP port that it listens on. If this is zero, or not
specified, the server is disabled.
Example AXTCP Client Interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This specifies a client which connects with the KIDDER node,
whose address is g8pzt.ath.cx, port 9393:
INTERFACE=5
TYPE=AXTCP
MTU=256
CONFIG=KIDDER g8pzt.ath.cx 9393
ENDINTERFACE
The CONFIG directive is used to specify a server, thereby
activating client mode. The format is as follows:
CONFIG=<servalias> <hostname | ipaddr> <tcp_port>
You may specify additional servers, by including a CONFIG for
each one. There is no limit to the number of CONFIG
directives that can be used with a single interface.
Combined AXTCP Client/Server Interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A combined interface is specified by including both INTNUM and
CONFIG directives. For example, this combines a server
listening on TCP port 9393 with 3 client connections:
INTERFACE=5
TYPE=AXTCP
INTNUM=9393
MTU=256
CONFIG=DORSET 216.23.45.91 10093
CONFIG=WALES gw3xr.dyndns.org 9394
CONFIG=Brum bm23.ath.cx 7507
ENDINTERFACE
This is just an example, and it could only be used at a
"static" node, in which case the client connections could
be replaced by AXIP or AXUDP anyway.
Such a configuration *couldn't* be used for "mobile" node,
because there's no way of directing incoming TCP port 9393 to
a mobile server!
AXTCP PORT Settings
~~~~~~~~~~~~~~~~~~~
A PORT attached to an AXTCP interface needs no special
configuration, and should simply be configured with
parameters (FRACK, RESPTIME, RFBAUDS) approriate to a high
speed connection, for example:
PORT=8
ID=AXTCP Operations
INTERFACENUM=5
FRACK=2000
RESPTIME=200
RFBAUDS=56000
ENDPORT
MAC parameters such as TXDELAY, TXTAIL, SLOTTIME, PERSIST,
FULLDUP, SOFTDCD etc. are meaningless for AXUDP, but FRACK,
RESPTIME, PACLEN, MAXFRAME, QUALITY etc. operate as normal.
On fast internet links you may wish to use a much lower FRACK,
say 2000ms, than on radio. It is not recommended that you
reduce it much below 1000ms, as it needs to be *at least*
twice the worst round-trip time plus the other end's RESPTIME.
RESPTIME is probably the one which will have most effect on
the responsiveness of the AX25 link, because it controls the
time delay between receiving a packet and sending an ACK. It
should be just a little more than the time it takes to receive
a maximum length packet. For example, at a data rate of
56Kbits/sec, a 256 byte packet lasts less than 50msec, so
RESPTIME=50 would be adequate. However the timing jitter due
to operating under Windows means that RESPTIME should be more
like 200ms.
By default, all AXTCP connections use the same PORT, but if
you prefer to use one port per neighbour, see the following
section. You must NOT attach more than one PORT to an AXTCP
interface.
Multiple Interfaces / Ports
~~~~~~~~~~~~~~~~~~~~~~~~~~~
A single AXTCP server can accommodate many clients, so there
is no practical need to use more than one AXTCP interface and
port.
This is analogous to having several nodes on the same radio
frequency, except that the nodes don't see each other's
transmissions, and there is no "hidden station" effect.
You may however prefer to assign each AXTCP partner to a
seperate port, analogous to having a dedicated radio
frequency for each neighbour. In this case you may configure
several interfaces, each with a single PORT attached.
The only proviso is that if INTNUM is used, no two AXTCP
interfaces may use the same INTNUM.
Transaction Logging
~~~~~~~~~~~~~~~~~~~
If the AXTCP option of LOGFLAGS is non-zero, XRouter logs
AXTCP connections and disconnections, otherwise nothing is
logged.
NOTES
When a client connects to a server, it should immediately be
possible to force an AX25 level 2 connection from either
client or server, by entering the command "C n ALIAS-1",
where n is the AXTCP port number, and ALIAS is the node alias
of the peer.
However, it may take a few minutes for the client and server
to commence NetRom operations, because each end must first
receive a nodes broadcast from the other. The link-up time
will be shorter if a prior link has been made recently. It
is hoped to speed up the linking time in a later version.
SEE ALSO
AXTCP-IFACE(6) -- AXTCP Interface.
AXIP(9) -- AX25-over-IP Encapsulation
AXUDP(9) -- AX25-over-UDP Encapsulation
XROUTER.CFG(8) -- Main Configuration File
AXUDP
AXUDP(9) XROUTER REFERENCE MANUAL 21/10/2023
NAME
AXUDP -- AX25-over-UDP Tunnelling.
DESCRIPTION
AXUDP is AX25 "encapsulated" within UDP datagrams. This
enables AX25 systems to communicate with each other via
TCP/IP networks (e.g. the Internet). The frame structure is
as follows:
.-----------.------------.------------------------.-----.
| IP header | UDP header | AX25 frame | CRC |
'-----------'------------'------------------------'-----'
(20 bytes) (8 bytes) (Typically 15-340 bytes)
It is slightly less efficient than AXIP, because there is an
extra 8 byte UDP header between the IP header and AX25
portion of the frame, but the difference is not significant.
One of the problems with AXIP is that many domestic routers
cannot be configured to route AXIP to a specific PC. And even
if they can, it can only be routed to one PC. This means you
can only have one AXIP node per public IP address.
The major advantage of AXUDP over AXIP is that it can usually
be handled by domestic Internet routers without problem. And
since UDP is a "ported" protocol (AXIP is "portless") you may
have more than one AXUDP node on the same public IP address,
by assigning them different UDP ports. The domestic router is
then able to route incoming packets according to UDP port.
The AX25 links created using AXUDP can in turn support NetRom
and amateur TCP/IP, just like real radio links.
OPTIONS
There are two main ways to set up formal AXUDP links, namely
"One-Link-Per-Port" (recommended) or "Many-Links-Per-Port"
(the BPQ way). Configuration of these is discussed later.
Although "One-Link-Per-Port" uses more PORTs, it is the more
flexible option. It is analagous to a full duplex radio link
on a private frequency. It allows all the link parameters to
be configured independently of any other link. It also allows
the traffic to be monitored and captured without clutter from
other traffic. It is more efficient in terms of processing,
and supports connections to any of the peer's callsigns,
SSIDs or aliases without any extra configuration.
The "Many-Links-Per-Port" option is analogous to a radio link
on a shared frequency. All ax25 connections have to share the
same PORT parameters, and it is difficult to monitor one link
without clutter from the others. It is computationally less
efficient, and only supports connections to pre-defined SSIDs
and aliases.
Both of the above methods can co-exist.
CONFIGURATION
Assuming you have a prospective AXUDP partner, both of the
above mentioned methods require steps 1 through 5 below:
1) Configure and test IP routing between you and your
partner. If you don't have reliable IP routing there's no
point in proceeding!
If you are linking via the Internet, it makes sense to
use the Internet IP addresses for this purpose, rather
than the amateur (44.x.x.x) ones, because the routing is
more reliable and the throughput is faster.
2) If your partner has a dynamic IP address, they must have
an account with a "dynamic DNS" provider, and you must
use the hostname thus provided for all operations. If
you use the IP address instead, the link will stop
working when the address changes.
3) If you wish to use your prospective partner's hostname
(e.g. "g8pzt.ath.cx") instead of their IP address, your
system needs access to a Domain Name Server (DNS). This
would usually be provided by Windows or Linux nowadays,
so you may remove all "DNS=" lines from XROUTER.CFG.
4) If using the partner's hostname, verify that
"PING <hostname>" resolves the address correctly.
5) Add an AXUDP interface to XROUTER.CFG as follows:
INTERFACE=9
TYPE=AXUDP
MTU=256
ENDINTERFACE
(Choose the interface number to suit yourself).
This interface can support an unlimited number of AXUDP
PORTs. You may define multiple interfaces if your ports
need different MTU's.
Only TYPE=AXUDP and MTU= are required, all other
parameters are ignored (at present).
Step 6 has two mutually exclusive alternatives. 6a is for
"One-Link-Per-Port" and 6b is for "Multiple-Links-Per-Port".
6a) One-Link-Per-Port:
For each AXUDP partner, add an AXUDP port similar to this:
PORT=8
ID=AXUDP link with VK1UDP
INTERFACENUM=9
IPLINK=27.69.88.73
UDPLOCAL=93
UDPREMOTE=93
FRACK=2000
RESPTIME=200
ENDPORT
You must specify at least ID, INTERFACENUM, and IPLINK.
IPLINK is the link partner's IP address or hostname. It
is more efficient to use IP addresses, if you are able to
do so, because it removes the need to resolve the
hostnames, but see (2) above.
UDPLOCAL and UDPREMOTE are the UDP "service port" numbers
for each end of the link, and if omitted they default to
93 (don't confuse these with *protocol number* 93, which
is AXIP). The numbers are independent, e.g. you may use
93 for UDPLOCAL and 10093 for UDPREMOTE).
MAC parameters such as TXDELAY, TXTAIL, FULLDUP, PERSIST,
SLOTTIME, SOFTDCD etc. are meaningless for AXUDP, but
Layer 2 parameters such as FRACK, RESPTIME, PACLEN,
MAXFRAME, QUALITY etc. operate as normal.
On fast Internet links you may wish to use a much lower
FRACK, say 2000ms, than on radio. It is not recommended
that you reduce it much below 1000ms, as it needs to be
*at least* twice the worst round-trip time plus the other
end's RESPTIME.
RESPTIME is probably the one which will have most effect
on the responsiveness of the AX25 link, because it
controls the time delay between receiving a packet and
sending an ACK. It should be just a little more than the
time it takes to receive a maximum length packet. For
example, at a data rate of 56Kbits/sec, a 256 byte packet
lasts less than 50msec, so RESPTIME=50 would be adequate.
However the timing jitter due to operating under Windows
means that RESPTIME should be more like 200ms.
6b) Multiple-Links-Per-Port
This mode requires only ONE port, configured similar to
the following:
PORT=8
ID=AXUDP links
INTERFACENUM=9
IPLINK=0.0.0.0
UDPLOCAL=10093
PEER=VK2DOT:DOTXR vk2dot.dyndns.org 9394
PEER=G8PZT-7 127.0.0.1 2345
PEER=G9DUM-3:DUMMY g9dum.ath.cx 10078
FRACK=2000
RESPTIME=200
ENDPORT
IPLINK must be present and must be exactly "0.0.0.0",
otherwise it won't work.
UDPLOCAL is the UDP service number on which XRouter
listens for incoming AXUDP packets. This MUST be different
from the service numbers used on any other PORTs.
Note that UDPREMOTE must NOT be used in this case. The
PEER statements are used instead.
7) If XRouter is indirectly connected to the Internet via an
intermediate router, that router will probably be using
some form of NAT (Network Address Translation) to share
one "public" IP address between several systems on your
LAN. The "front end" router will probably route outgoing
AXUDP without problem, but it will not know where to send
incoming AXUDP unless explicitly configured.
Configuring such a router for AXUDP usually involves
specifying a UDP port number (your UDPLOCAL as specified
above), and the LAN IP address of a machine to which it
should be routed, i.e. Xrouter's LAN IP address. This is
sometimes called "port forwarding". There are websites
(e.g. portforward.com) dedicated to showing you how to do
this for most makes of router.
Some routers don't have the facility to open specific UDP
ports, but at the very least should allow you to direct
all UDP traffic to a specified IP address.
8) Your link partner must set up a reciprocal arrangement,
i.e. their UDPREMOTE must match your UDPLOCAL and vice
versa.
If everything has been set up correctly, you should be able
to connect with your new neighbour node immediately, at least
at AX25 layer 2. You can test this by entering the command
"C n ALIAS-1", where n is the PORT number of your link, and
ALIAS is the node alias of your link partner. If this doesn't
work, you or your partner have made a mistake somewhere in
the configuration.
Even if everything is configured correctly, it may take a
while for NetRom to configure itself for the new link, as the
nodes need to exchange NODES brodcasts first. Once they have
done so, there should be no delays in future.
NOTES
You may of course use AXUDP to communicate between nodes on
the LAN, or even on the same machine.
If you have more than one node on your LAN using AXUDP, your
UDPLOCAL must not be the same as the UDPLOCAL (or equivalent
thereof) of any other node on your LAN. There are two
reasons for this; Firstly, for a given UDP port, NAT routers
cannot direct direct incoming traffic to more than one LAN IP
address at a time. Secondly, only one application on a PC
may "own" a given UDP port number.
Unlike other software, you *DO NOT* need a different UDPLOCAL
for each AXUDP port. It is quite common for link partners to
specify that they will transmit AXUDP to you on a UDP port
that is different to your other UDPLOCAL settings. There is
absolutely *NO* valid reason for this! It makes life more
complicated for you, and you have to set up extra "port
forwarding" entries in your NAT router. For these reasons
you are strongly advised to use the same UDPLOCAL for all
AXUDP partners on a given node. As a rule, you may NOT tell
a link partner what his UDPLOCAL should be, no more than he
should dictate what your UDPLOCAL should be. Instead, he
should specify which UDP port he is listening on (which
becomes your UDPREMOTE), and in return you tell him which UDP
port you are listening on (which becomes his UDPREMOTE).
DO NOT set up an AXUDP link to a link partner with whom you
already have an AXIP link. This is a common mistake, and is
likely to cause problems!
IP ROUTING
As mentioned earlier, you may route amateur IP (44.x.x.x)
over your new AXUDP link, and are encouraged to do so. Whilst
the amprnet purists will argue that this is not as efficient
as IP-over-IP (since it uses a few more bytes), it is a LOT
easier to set up, and doesn't require that your domestic
router and operating system can route IP-over-IP (many
routers are not able to route incoming IP-over-IP to a
specific PC, and Windows' IP stack blocks IP-over-IP).
To route amateur IP over an AXUDP link, simply add an IP
route entry directing the required subnet to your neighbour's
IP address on the AXUDP port using datagram mode. For
example, if the AXUDP port is port 8, and the link partner
(44.136.20.2) is able to accept all amprnet traffic for
Australia, the entry would look like this:
IP ROUTE ADD 44.136.0.0/16 44.136.20.2 8 d
The source IP address for this mode of routing is the
IPADDRESS of the AXUDP port. Therefore, if XRouter's main
IPADDRESS (in XROUTER.CFG) is not a 44-net address, you must
override it with a 44-net address on the AXUDP port. If the
main IPADDRESS is a 44-net address, which is the recommended
configuration, do not specify IPADDRESS in the PORT
configuration block.
SEE ALSO
AD-HOC(9) -- Ad-Hoc Networking.
AXIP(9) -- AX25-over-IP Encapsulation
IP(1) -- IP Routing / Configuration Commands.
IPENCAP(9) -- IP-in-IP Encapsulation.
IPLINK(1) -- Display / Set a Port's IPLINK.
IPLINK(7) -- Peer Address of a Link.
IP-PRIMER(9) -- IP Addressing / Routing Primer.
IPROUTE.SYS(8) -- IP Routing / Configuration File.
LEARN(7) -- Learn Unsolicited AX*P Peer Details.
UDPLOCAL(1) -- Display / Set a Port's UDPLOCAL.
UDPREMOTE(1) -- Display / Set a Port's UDPREMOTE.
XROUTER.CFG(8) -- Main Configuration File
BCAST
BCAST(9) XROUTER REFERENCE MANUAL 21/10/2023
NAME
BCAST -- UI Broadcasting.
DESCRIPTION
XRouter has the ability to "re-broadcast" a received UI frame
onto several ports at once. This can be thought of as a
"one-to-many" PIPE, but there are subtle differences:
Whereas pipes conduct all frames of the selected type(s),
virtually regardless of source and destination addresses
(unless they are selective pipes), the broadcast function
acts only upon UI frames, and only if the source and
destination addresses match those specified by the sysop.
Another difference is that frames may be broadcast to
different groups of ports depending on the destination
address. For example, FBB unproto headers from a BBS may be
rebroadcast on certain user-access ports only, while mail
beacons may be distributed to a different, possibly
overlapping, set of ports.
You may alternatively use this feature as a "filtered pipe"
between two ports, allowing only UI frames with acceptable
source and destination callsigns to pass through.
Note that this feature does not require a "connection" to
XRouter, it is purely an unconnected mode. It was developed
to allow BBS's to distribute mail beacons and "unproto" mail
headers. You may use it (or not) how you wish.
You should be aware that broadcast traffic takes precedence
over all other frames, so an excessively high level of
broadcast activity may cause other outbound traffic on the
destination port to be delayed. However, it is unlikely that
anyone will notice this effect unless the channel is
seriously overloading.
Broadcasting is controlled by two keywords in each PORT
section of the XROUTER.CFG file. The first keyword is BCAST,
which is used to specify the destination addresses to be
broadcasted.
For example, BCAST=MAIL,FBB will re-broadcast received
non-digipeater UI frames addressed either to FBB or MAIL.
The frames addressed to FBB will be broadcast on all ports
which have FBB in their BCAST list, and those addressed to
MAIL are broadcast on all ports which have MAIL in the BCAST
list.
If no matching ports are found, the frame is broadcast only
on the port upon which it is received. If you don't need the
broadcast function, simply omit (or comment out) the BCAST
directive.
The second keyword is BCFROM, which is used to specify a list
of callsigns from whom frames will be accepted for broadcast.
You may use this to restrict the broadcast facility to
certain senders only. BCFROM applies only to frames
*directly* received on the port for which it is specified.
e.g. BCFROM=GB7PZT,GB7MAX stipulates that only frames from
GB7MAX and GB7PZT will be accepted for broadcast. If the
keyword is omitted, the broadcast facility is unrestricted.
For both keywords, the list of callsigns must be separated by
commas, and must include no spaces.
CAVEATS
Be careful not to configure BCAST and PIPE together in a way
which causes infinite loops. This is a common cause of
crashes.
SEE ALSO
BCAST(7) -- Destinations for UI Broadcasting.
BCFROM(7) -- Approved UI Broadcasters.
PIPES(9) -- Frame Pipes.
XROUTER.CFG(8) -- Main Configuration File.
CHARGEN
CHARGEN(9) XROUTER REFERENCE MANUAL 7/9/2023
NAME
CHARGEN -- Character Generator Service
SYNOPSIS
This file describes XRouter's Character Generator service,
which is intended for testing purposes.
DESCRIPTION
The CHARGEN service generates a stream of characters for
testing purposes. It is very bandwidth hungry and should be
used with caution. It uses the same "well known" service
number (19) as the TCP/IP version.
Upon opening a connection to NetromX service 19, the server
starts sending lines of characters to the caller, and
continues until the caller send "/x" followed by newline,
or closes the connection. The server accepts no other
commands.
Conforming to the de-facto standard, each line of 72
characters is offset by one. This creates a pattern which
makes it easy to spot dropped characters. Here's an idea
of what it looks like:
c g8pzt 19
G8PZT-1:MOBILE} Trying G8PZT::19...
G8PZT-1:MOBILE} Connected to G8PZT::19
"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ
#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[
$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\
%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]
&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^
'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_
()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`
)*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`a
and so on...
SEE ALSO
SERVICES(9) -- NetRomX Services.
CHAT-SRV
CHAT-SRV(9) XROUTER REFERENCE MANUAL 21/10/2023
NAME
CHAT-SRV -- CHAT Server.
DESCRIPTION
XRouter's integral chat server allows groups of users to hold
live multi-way conversations without having to manage several
TNC streams at once.
It is available to all callers, and is accessed by using the
CHAT command at the main prompt, or by connecting to NetRomX
service 2, or by connecting directly to the server's callsign
or alias. TCP/IP users can additionally access it by
TELNETting to port 3600 (this port can be reassigned or
disabled using the CHATPORT directive in XROUTER.CFG).
Sysops have a "always-on" chat window for chatting amongst
themselves on channel 1234, and there is a "chat monitor"
window for keeping an eye on chat activity.
The server is tri-standard, i.e. it can exist on, and
interact with, 3 completely different types of chat network
simultaneously, namely XRchat, "Tampa Ping Pong Converse",
and W0RLI RoundTable chat, as used by BPQ.
XRouter's chat server is a fully functional RoundTable node,
however data is NEVER transferred between networks. e.g. what
is said on the RoundTable network is never propogated around
the XRchat network and vice versa.
Channels
~~~~~~~~
The "XRchat" system has 32767 channels or " chat rooms", each
of which can support an unlimited number of users, so it is
possible for groups to have their own "private" room, or to
reserve certain rooms for specific topics.
Channels 1 to 255 (except 101 - see below) are "local" to
each chat server, and the remaining channels 256-32767 are
"global", i.e. they are linked with all other XRouter chat
servers, providing there is at least one link set up with
another server.
Room 101 is a gateway to the W0RLI "RoundTable" / BPQChat
network, providing there is at least one link with a
RoundTable or BPQChat peer. Within room 101, users may create
and occupy private chat spaces called "topics". The default
topic at login is "general".
In addition to the "positive" channel numbers, there are
another 32768 channels numbered 0 to -32767. These
correspond to channels 0 to 32767 on the "Tampa Ping Pong"
system.
XRouter allows only limited interconnection between these two
systems, because the channel layouts and topologies are
completely incompatible. XRchat was specifically designed
for use on an anarchic, slow radio network, whereas Ping-Pong
requires a more planned network topology to avoid loops, and
is largely carried on Internet links. The sheer volume of
chat in the Ping-Pong system would overwhelm marginal radio
links.
Data received from Ping-pong is not propogated via the
XRouter chat interlinks and vice versa. In effect, XRouter
can be a stub Ping-Pong host, but not part of the Ping-Pong
backbone.
Channel 1000 is the default channel to which users are
assigned at log-on, but they may set their preferred login
channel using the "/CHANNEL DEFAULT" command.
Users may "join" as many channels as they wish, so they may
take part in several separate conversations at once. Users
may listen on any number of positive and negative channels
simultaneously, but may only *send* on one channel at a time.
Once logged onto a channel, anything sent by the user is
copied to all other users of that channel, except for lines
beginning with a forward slash (/), which are interpreted as
chat server commands. The distributed text is prefixed by
the channel number and the sender's callsign and name, to
allow the recipients to identify who sent it.
Commands
~~~~~~~~
All chat server commands begin with a forward slash (/), and
most of them may be abbreviated to the initial letter. The
/? command shows the available commands and syntax, while
/HELP gives more details.
The /NAME command is used to enter the user's first name, and
serves as a "login". Users are not permitted to join any
channels until they have supplied a name. TCP/IP users must
additionally supply a callsign with the /USER command.
/CHANNEL, /JOIN and /LEAVE are used to select the desired
channel, /WHO shows the active channels and who is using them,
and /QUIT terminates the chat session. The full command set
is shown in more detail in the command reference section.
Users who log on to more than one chat server at once are
treated as separate entities, and must supply their name and
callsign on each server. Note that the RoundTable network
does not allow a user to be logged on at more than one server,
but there are often valid reasons for doing so, therefore the
XRchat protocol allows multiple logins by design.
Configuration
~~~~~~~~~~~~~
The chat server is fully automatic and requires minimal
setting up. It is configured using entries in XROUTER.CFG as
follows:
CHATCALL defines the chat callsign for AX25 and NetRom
operations. A SSID of -8 is strongly recommended for all
XRchat systems.
CHATALIAS specifies the alias for AX25 and NetRom operations.
It is recommended that this should begin with something
geographically relevant, and end with "CHT" e.g. BHMCHT for
Birmingham, LDSCHT for Leeds etc., so it can be easily
identified in node tables.
CHATQUAL specifies the NetRom "quality" assigned to the chat
server and alias for L3/4 operations. If set to 0, the server
will not be visible on the network.
A setting of 255 makes the chat server as visible as the
node, which just fills up the nodes tables. A value somewhere
in between, to give medium visibility, is suggested.
CHATLOG specifies the amount of detail that is logged. A value
of 0 suppresses logging. Add together the values corresponding
to the desired options from this table:
1 Local user connect / disconnect event
2 Remote user connect / disconnect event
4 Peer server connect / disconnect event
8 Local channels 1-255 join / leave events
16 Public channel join / leave events
32 Log channel notifications
64 Log the text of conversations
128 Use a single logfile, instead of daily ones
CHATPORT adjusts or disables the TCP port which the chat
server normally listens on. The default is 3600, but you may
need to adjust this if you have another system or application
using that port.
CHATLINKS specifies the callsigns of other servers to link to.
- Only NetRom links are allowed with RoundTable/BPQChat peers.
- Only TCP/IP links are allowed to Tampa Ping-Pong peers.
- Links with XRChat peers may use either NetRom or TCP/IP,
but NetRom is the norm.
If NetRom linking is used, you must specify the peer's
CALLSIGN not the alias. The peer's callsign and alias must
exist in your nodes table, i.e. you can't link with peers
beyond the NetRom "horizon".
Unilateral linking is not allowed, and will not work. You
*must* co-ordinate it with your peers, such that you are in
their CHATLINKS list and they are in yours.
You should avoid linking to peer servers via slow links. If
the link isn't up to the job, frames will be dumped, and the
users will therefore get a poor service.
Peer links may be added and removed at any time using the
/LInks command.
Links With XRouter Peers
~~~~~~~~~~~~~~~~~~~~~~~~
NetRom links with XRouter chat peers are specified in
XROUTER.CFG as follows (you can put several peers in one
CHATLINKS directive, or use one directive per link, or any
combination thereof):
CHATLINKS=<netrom_call>,<netrom_call>,...
e.g. CHATLINKS=GB7GH-7,GB7BM-8,N0LBA-8
or at the chat command prompt:
/LI ADD <netrom_call>
e.g. /LI ADD GB7BX-9
For TCP/IP links with XRouter chat peers, the IP address and
TCP "port" number must be specified, along with the CHATALIAS
of the peer server, and you can only specify one peer per
line.
CHATLINKS=<ip_address>:<tcp_port> <peer_alias>
e.g. CHATLINKS=67.69.96.23:3600 KDRCHT
or at the chat command prompt:
/LI ADD <ipaddress>:<tcp_port> <peer_alias>
/LI ADD 67.69.96.23:3600 KDRCHT
Links with RoundTable/BPQ Peers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Links with RoundTable/BPQ chat servers are defined similarly
to the XRchat NetRom case, except that the peer callsigns
must be prefixed with a '+', for example
CHATLINKS=+XE1FH-11,+N1FGR
or /LI ADD +XE1FH-11
The '+' is very important - it tells XRouter to use
RoundTable protocol instead of XRchat protocol!
Links with Tampa Ping-Pong Peers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Links with Tampa Ping-Pong converse servers are specified in
XROUTER.CFG as follows. Note the <peername> is prefixed with
a '*' to distinguish it from an XRchat TCP entry:
CHATLINKS=<ip_address>:<tcp_port> *<peername>
e.g. CHATLINKS=80.195.22.67:3601 *brmcht
Alternatively, use the /LINK ADD command
/LI ADD <ipaddress>:<tcp_port> *<peername>
e.g. /LI ADD 80.195.22.67:3601 *brmcht
FILES
The chat server stores user accounts in the CHAT subdirectory,
and reads its HELP files from CHAT/HELP/ subdirectory.
If transaction logging has been enabled by a non-zero CHATLOG
directive in XROUTER.CFG, chat server activity is recorded in
the LOG subdirectory. If the "use single logfile" option is
enabled, everything is logged to file CHATSERV.LOG, otherwise
it is logged to dialy logfiles with names in the form
yymmddCH.LOG, where yymmdd are the year, month and day.
AVAILABILITY
The chat server is available to all users. It is also
available via the HTTP and MQTT interfaces.
SEE ALSO
CHAT(1) -- CHAT command.
CHATCMDS(1) -- Chat server commands.
CHATALIAS(7) -- Chat Server Alias.
CHATCALL(7) -- Chat Server Callsign.
CHAT-SVC(9) -- NetRomX Chat Service.
CHATPORT(7) -- TCP Port for Chat Server.
MQTT-CHAT(9) -- MQTT Interface to Chat Server.
XROUTER.CFG(8) -- Main Configuration File.
CHAT-SVC
CHAT-SVC(9) XROUTER REFERENCE MANUAL 22/9/2023
NAME
CHAT-SVC -- NetRomX CHAT (Converse) Service.
DESCRIPTION
NetRomX "standard service" no. 8 connects to XRouter's
integral chat server. This server allows groups of users to
hold real-time (and non-real-time) text conversations.
The service is used by the "CHAT <nodecall>" command, but is
open to all, and no login is required.
The server has a comprehensive set of commands, which all
begin with a forward slash (/), for example /HELP. These are
fully documented in the CHATCMDS manual pages, and in the
chat server's own HELP system.
SEE ALSO
CHAT(1) -- CHAT command.
CHATCMDS(1) -- Chat server commands.
CHAT-SRV(9) -- Chat Server.
SERVICES(9) -- NetRomX Services
DAYT-SVC
DAYT-SVC(9) XROUTER REFERENCE MANUAL 7/9/2023
NAME
DAYTIME -- DAYTIME Service.
DESCRIPTION
The DAYTIME service returns the node's current local date and
time, for test or general interest purposes. It is accessed
via NetromX standard service 13.
Upon connection to service 13, the server sends the local
time as a single line of text. The response is currently like
this, but may change in future to include timezone and DST:
Thu May 20 16:37:24 2021
When the caller has received the text, the server terminates
the connection.
SEE ALSO
SERVICES(9) -- NetRomX Standard Services.
DEDHOST
DEDHOST(9) XROUTER REFERENCE MANUAL 21/10/2023
NAME
DEDHOST -- WA8DED Hostmode Emulation.
DESCRIPTION
XRouter can emulate a WA8DED TNC, in both "normal" mode and
"host" mode. This can be used for both manual operations and
application support, just like a real TNC. Many applications
are capable of using WA8DED host mode. See the MAN page for
WA8DED for details of normal emulation mode.
.---------. .-----.
User -->| XRouter |------RS232-------| BBS |
'---------' '-----'
The application may be located on the same machine as
XRouter, connected to it either via a pair of "virtual" COM
ports, or via a pair of "real" COM ports interconnected with
a null-modem cable.
Alternatively, the application may be located on a seperate
machine, using an RS232 null-modem cable to interconnect the
machines.
Configuring XRouter To Support Applications
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1) Decide how to interconnect the application and XRouter.
You can use either a pair of real COM ports and a
null-modem cable, or a tty/pty pair
2) Add an INTERFACE.
In XROUTER.CFG specify an interface similar to this, where
"x" represents the interface number...
INTERFACE=x
TYPE=ASYNC
COM=/dev/ttyUSB0
PROTOCOL=DEDHOST
APPLNUM=3
CHANNELS=4
SPEED=9600
FLOW=0
MTU=256
ENDINTERFACE
COM is the name of the serial device used to link to the
application (on DOS / Windows this would be a COM number).
CHANNELS specifies the max no. of host channels the
interface will provide (between 1 and 32). The total
number of host channels available to be shared between all
applications is 64. If XRouter cannot allocate the
requested number of channels it will fail to start. (In
versions up to 200e the number of channels was specified
by INTNUM. This is now deprecated.)
MTU must be 256
APPLNUM (1-16???) specifies which application is using
this interface. Corresponds to "n" in APPL=n (see below).
SPEED is the serial baud rate . Don't use too low a speed,
otherwise badly-written applications may lose sync due to
the time it takes for a poll to reach XRouter and the
reply to reach the application. Speeds of 9600 and above
should be OK.
FLOW must always be set to 0 or 4. Setting FLOW to any
value other than 0 or 4 may cause the application or
XRouter to hang. FLOW=4 is a special case which forces
the WA8DED emulator to default to host mode (see later).
- Don't use CHANNEL, IOADDR, or INTNUM keywords.
- Don't try to attach any PORTs to this interface, as they
are not required.
3) Define an Application:
In XROUTER.CFG add an APPL=n block, to specify the
application's callsign, alias, Netrom quality and
visibility. The "n" parameter must match the APPLNUM
specified in the INTERFACE block. For example:
APPL=3
APPLNAME=BBS
APPLCALL=GB7PZT
APPLALIAS=PZTBBS
APPLQUAL=100
APPLFLAGS=4
ENDAPPL
The application definition (APPL) block should contain one
or more of the following keywords:
APPLNAME is the nickname or shortcut by which the
application is accessed from the XRouter's
command line. In the example above, if a user
types "BBS" at the command prompt, they will be
connected to the application.
APPLCALL is the AX25 layer 2 callsign which the
application will use. If specified, the
application will accept AX25 L2 connects to this
callsign, subject to the setting of APPLMASK
(see below).
APPLALIAS is the AX25 layer 2 "alias" for use by the
application. If specified, the application will
accept AX25 L2 connects to this callsign, subject
to the setting of APPLMASK (see below).
APPLQUAL (0-255) is the Net/Rom quality to broadcast. If a
non-zero value is specified here, the APPLCALL
will be included in Net/Rom nodes broadcasts and
the application will be connectible at AX25 layer
4. The higher the quality, the further the node
entry will propogate.
APPLFLAGS defaults to 0 if omitted. A value of 4 instructs
XRouter to send "Connected to (applcall)" to the
user upon connection to an application. This may
be omitted if the application sends its own
"Connected to" message.
All fields within an application definition block are
optional - you may have for instance choose to have an
APPLNAME but no APPLCALL, meaning the application could
only be reached by typing the applname at the command
prompt. Or you could have an APPLCALL but no APPLNAME, in
which case the application would be directly connectible,
but wouldn't be reachable from a command line shortcut.
4) Set Application Visibility.
In XROUTER.CFG set the APPLMASK on each PORT that you wish
the application to appear on. The application will only
monitor traffic and send UNPROTOs on the ports which have
the application enabled via the APPLMASK.
The APPLMASK parameter specifies which applications are
directly connectible on a port. The default is 255, which
allows all applications. The value is made up by adding
together the required options from the following numbers:
1 - Enable Application 1
2 - Enable Application 2
4 - Enable Application 3
8 - Enable Application 4
16 - Enable Application 5
32 - Enable Application 6
64 - Enable Application 7
128 - Enable Application 8
Example: APPLMASK=5 (enable applications 1 and 3)
If you want an application to be directly connectible on a
port, it must have either an APPLCALL or an APPLALIAS (or
both), and the corresponding bit in that port's applmask
must be set.
5) Configure The Application
Finally, configure the application to use WA8DED hostmode
on the other of the chosen COM port pair, with the same
baud rate as specified in the INTERFACE block.
Default Mode
~~~~~~~~~~~~
The default mode (host mode / terminal mode) is controlled by
the FLOW parameter in the INTERFACE definition block. With
FLOW=0, XRouter's WA8DED emulation starts in non-host
("terminal") mode because most applications expect it that
way, therefore it allows them to sync up quickly.
However, some applications may expect the TNC to be in host
mode, and may fail to sync if FLOW=0. In this case, setting
FLOW=4 forces the WA8DED "TNC" to start in host mode.
This control is not a panacea. For example, If XRouter is
stopped and restarted while an application is running in
hostmode, everything should quickly sync up again if FLOW=4.
But this setting may prevent the application from syncing up
from cold.
Starting / Stopping Applications
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Where possible, XRouter should be started before the
application, and stopped after it, because some applications
malfunction if they don't see the expected responses when
they start up and shut down.
If an application doesn't close down "cleanly", it may take a
while to resync when it restarts. This is normal.
Hidden Applications
~~~~~~~~~~~~~~~~~~~
If you have an application that only makes outgoing
connections, you can omit the APPL block altogether. The
application will still work, but it won't accept incoming
connects.
Known Issues
~~~~~~~~~~~~
a) FBB 16-bit versions 700g and 700i use 100% CPU when
configured for WA8DED hostmode. The BBS seems to work OK
despite this. Although this is not an XRouter issue, we
are looking at ways to fix the problem.
b) WinFBB v701-35 often reports "Error initialising WA8DED
Driver" and fails to communicate with XRouter after that.
It usually boots cleanly if stopped and restarted. The
best setting for FLOW is 0.
c) With WinFBB v701-35, the sysop is able to open a gateway
connection to XRouter's command processor and make
outgoing connections. However, whilst incoming
connections are accepted, WinFBB only sends the SID
[FBB-701-ABFHMR$] and nothing else. It doesn't respond to
any command.
d) If XRouter is stopped and restarted within a short time,
WinFBB v701-35 will resync cleanly. However, if too long
an interval elapses before XRouter restarts, WinFBB goes
into meltdown and will never resync.
e) Although WinFBB 701-35 appears to run in DED mode, it
doesn't run properly, and is therefore unusable as a BBS
in this mode.
f) If Com0Com is used without the "enable buffer overrun"
option checked, closing the application may sometimes
cause XRouter to hang until the application is restarted.
Breaking out of host mode
~~~~~~~~~~~~~~~~~~~~~~~~~
If the emulator is inadvertently switched into, or left in,
host mode it can be easily be returned to terminal mode using
Hyperterm as follows:
- Send ctrl-a's slowly (1 or 2 per sec) until "INVALID
COMMAND" appears (it may take up to 256 ctrl-a's to make
this happen, but usually it will take a lot less). Stop
sending ctrl-a's as soon as the response appears. If you
inadvertently send one or two too many, *slowly* send up to
4 more ctrl-a's and the message should appear again.
- Send JHOST0 (there will be no response)
- Send <esc> and it should display the "* " to indicate that
it is in command mode.
Troubleshooting
~~~~~~~~~~~~~~~
1) XRouter reports "All Host Ports in use" upon first attempt
to connect to DEDHOST application:
- The APPLNUM in the INTERFACE definition block does not
match the application number specified in the APPL
definition block.
2) Application frequently loses sync:
- Serial port baud rate too low?
If the baud rate is too low, the data may take too long
to propogate back and forth between XRouter and the
application, causing the application to think it has
lost sync. Good applications would adjust their polling
rate according to the baud rate. Unfortunately some
don't!
- Serial port baud rate too high?
If the baud rate is too high the serial line may drop
characters, causing loss of sync. Another, more likely,
issue is that with high baud rates the "timeout" between
the application sending a poll and expecting a reply may
be too short for a multitasking operating system, even
though it is OK for a firmware TNC.
- FLOW not set to 0 or 4
- The PC is too busy.
Unlike a real TNC, XRouter does not have sole use of the
CPU. Other processes may "steal" CPU time, causing a
delay in responding to the application's polls. In most
cases this shouldn't happen, but some applications poll
too fast. The only solution is to avoid running
CPU-hungry applications on the same PC.
- Excessive tracing on XRouter's console.
Writing characters to the console is very CPU-intensive,
so having MON ON can cause delays in the poll-response
cycle if the amount of trace traffic is heavy. Turning
MON OFF or tracing fewer ports should alleviate the
problem.
3) XRouter hangs when application is stopped:
- XRouter's RS232 output buffer is full and something is
preventing it from emptying. - If using Com0Com virtual
COM port emulator, check the "Enable buffer overrun"
boxes - Use FLOW=0.
4) Application won't sync if XRouter is stopped and restarted
- XRouter's DEDHOST emulation starts in non-host mode
because most applications expect it that way. This
allows them to sync up quickly when they are started
AFTER XRouter. However, if XRouter is restarted while
the application is running, the application won't know
that XRouter is back in non-host mode, and will fail to
sync.
5) Can't connect to application on port N / Can't monitor
port N
- The port's APPLMASK is not set correctly (see above for
description of APPLMASK)
- There is a bug in early versions - Although up to 16
applications are allowed, if APPLNUM is more than 8, the
application cannot be connected to.
6) Application is monitoring port N uncesessarily.
- The default APPLMASK setting for each port allows access
to, and monitoring by, all applications. If you wish to
suppress connections and monitoring on a particular
port, you must set APPLMASK accordingly. To suppress all
applications, set the port's APPLMASK to 0.
Random Factoids...
~~~~~~~~~~~~~~~~~
- Uplinks and downlinks to DEDHOST applications show as link
type "DED" on XRouter's "Users" display.
SEE ALSO
WA8DED(9) -- WA8DED TNC Emulation.
XROUTER.CFG(8) -- Main Configuration File.
DHCP
DHCP(9) XROUTER REFERENCE MANUAL 21/10/2023
NAME
DHCP -- Dynamic Host Configuration Protocol.
DESCRIPTION
The acronym DHCP stands for Dynamic Host Configuration
Protocol. This is a client-server based protocol which
allows clients on a TCP/IP network to obtain their
configuration parameters from a server.
The protocol supports the transfer of a wide range of
configuration parameters such as the client's IP address,
netmask, DNS and gateway addresses, plus TCP/IP parameters
such as MSS, but is most commonly used to allocate dynamic
IP addresses to clients.
IP addresses are "leased" to clients for a period of time,
after which the client must renew the lease. Servers
generally attempt to re-assign the same IP address to the
same client.
DHCP in XRouter
~~~~~~~~~~~~~~~
XRouter includes a DHCP client, and a DHCP server may be
included in future, if the need arises. The full range of
configuration options is not supported, since in most XRouter
application scenarios they are not required. The options
currently supported are client's IP address and lease time,
DNS and gateway IP addresses.
The DHCP client is available only on Ethernet interfaces
which are using the EXTERNAL driver. Lease negotiation and
renewal are completely automatic, and the sysop need not be
concerned with the process.
Do you need DHCP?
~~~~~~~~~~~~~~~~~
If you wish to connect XRouter to an ISP via a cable modem,
e.g. to use it as an Internet Connection Sharing router, you
will probably need DHCP if your ISP uses dynamic IP
addressing. However, if your ISP assigns you a static IP
address you won't need DHCP.
You will not need DHCP if your connection to the ISP is via
dial-up PPP, because dynamic IP addresses are assigned as
part of the PPP negotiation process.
*** The above scenarios date back to the time when domestic
routers had not yet become commonplace, when Windows
"Internet Connection Sharing" was in its unreliable infancy,
and XRouter was running on DOS machines. Nowadays, with
modern ADSL and cable routers, and proper TCP/IP built into
Windows, it is unlikely that XRouter would be required to
provide the Internet Connection Sharing service.
The only reason you might wish to use DHCP these days is to
obtain a dynamic LAN IP address from your domestic router,
but this is not recommended practice. It is far better to use
static IP addresses when feasible, especially when you are
"port-forwarding" TCP and UDP ports to specific machines.
You do not need DHCP for normal amateur radio operations.
Enabling DHCP
~~~~~~~~~~~~~
In XROUTER.CFG, put "DHCP=1" in the appropriate port
definition block. There is no need to specify a port
IPADDRESS because one will be assigned by the DHCP server.
If however, a port IPADDRESS is specified (or it is not
specified but a global IP address is specified), that address
will be used for non-DHCP traffic until DHCP succeeds in
leasing a (possibly different) address. If the global
IPADDRESS is 0.0.0.0 or not specified, it will be assigned
by the first client which obtains a lease.
To disable DHCP, put "DHCP=0" in the PORT definition block,
or simply omit the keyword altogether.
The DHCP command displays DHCP status information, and is
detailed in DHCP(1).
SEE ALSO
DHCP(1) -- DHCP Commands.
DHCP(7) -- Obtain Port IP Using DHCP.
XROUTER.CFG(8) -- Main Configuration File.
DISC-SRV
DISC-SRV(9) XROUTER REFERENCE MANUAL 21/10/2023
NAME
DISC-SRV -- DISCARD Server.
DESCRIPTION
The DISCARD server is a "sink" session, whereby XRouter
ignores (discards) everything sent to it. This is a useful
tool for testing connections, throughput etc.
The server is accessed either by connecting to TCP port 9,
or by connecting to NetRomX serice number 9, or by issuing
the DISCARD command at XRouter's command prompt.
The service terminates upon receipt of "/x" followed by
newline, or when the caller disconnects.
The server is always available on NetRomX service 9, and
from the command line. It is available by default on TCP,
but that can be changed using the DISCARDPORT=n directive in
XROUTER.CFG. Setting the port to zero disables direct TCP
access to the server.
SEE ALSO
DISCARD(1) -- DISCARD Command.
DISC-SVC(9) -- NetRomX Discard Service.
SERVERS(9) -- Servers In XRouter
TCP-PORTS(6) -- TCP Service Ports.
XROUTER.CFG(8) -- Main Configuration File.
DISC-SVC
DISC-SVC(9) XROUTER REFERENCE MANUAL 22/9/2023
NAME
DISC-SVC -- NetRomX DISCARD Service.
DESCRIPTION
NetRomX service 9 is a DISCARD server. This is a "sink"
session, whereby XRouter ignores (discards) everything sent
to it. This is a useful tool for testing connections,
throughput etc.
The service terminates upon receipt of "/x" followed by
carriage return (ascii 13) , or when the caller disconnects.
No other commands are accepted.
The DISCARD server can also be accessed from XRouter's
command prompt, or by connection to TCP port 9, unless the
sysop disables it).
SEE ALSO
DISCARD(1) -- Start a Discard Session.
DISC-SRV(9) -- About the Discard Server
SERVICES(9) -- Servers In XRouter
TCP-PORTS(6) -- TCP Service Ports.
DISC-SVC(9) END OF DOCUMENT
DNS-SRV
DNS-SRV(9) XROUTER REFERENCE MANUAL 17/10/2023
NAME
DNS-SRV -- Domain Name Server.
DESCRIPTION
XRouter includes a basic DNS (Domain Name System) server,
which can answer DNS queries from other systems via the
standard UDP port 53.
This is a legacy from DOS XRouter, and is unlikely to be of
much practical use on the LAN port, since Windows / Linux can
perform the same function.
However, it may be of use via the radio and SLIP / PPP ports.
The server only answers one query per message. Only standard
queries for type A are currently answered. Recursion is
supported. Other query types may be supported in a later
version, if anyone requests that functionality.
The server can act as a DNS proxy, allowing XRouter to
function as an Internet Connection Sharing router for a
network of clients. The clients on the local "intranet" send
their DNS queries to XRouter, which either resolves them using
its own DNS lookup (DOMAIN.SYS), or queries an external DNS on
their behalf if necessary.
The "intranet" mentioned above could be hosts linked via SLIP,
PPP or even an IP-over-ham-radio LAN.
SEE ALSO
DOMAIN.SYS(8) -- Domain Resolution File.
DUN
DUN(9) XROUTER REFERENCE MANUAL 17/10/2023
NAME
DUN -- Dial-Up Networking.
DESCRIPTION
Dial-Up Networking (DUN) is a subsystem which allows XRouter
to connect to other TCP/IP systems via a dial-up Public
Switched Telephone Network (PSTN) link.
This could be used for example to connect with an Internet
Service Provider (ISP), enabling XRouter to link to other
systems via the Internet. Or (if you have unmetered telephone
calls) it could be used for linking one XRouter directly with
another via the PSTN on demand.
DUN basically consists of:
a) A script reader capable of configuring PPP,
controlling a modem and logging into a remote system.
b) A system to invoke these scripts when required.
Configuring DUN
~~~~~~~~~~~~~~~
Please see the manual section entitled "PSTN modem support"
for details of how to configure XRouter to use a modem.
Assuming you have a port configured for modem use, DUN
requires at least one dialler script, to control the dial and
login sequence.
Dialler scripts are ordinary text files containing script
commands as detailed below, one per line. Lines must not
exceed 256 characters in length. The script file can be named
as you wish, for example you might like to name your AOL dial
script "AOL.SCR". You will need to use this name later to
identify the script, so it makes sense to call it something
meaningful, rather than "SCRIPT1.TXT". Script files must
reside in the same directory as XRouter.EXE.
Next you must configure DUN to invoke your script whenever a
connection is required. This is done by using the DUN ADD
command to record the peer's IP address and the name of the
script used to make the connection to that peer. If you don't
know the IP address you may use a "dummy" address, e.g.
"1.1.1.1", because it is simply a handle used to invoke the
appropriate script. You should use one DUN ADD command for
each script.
Finally, you must add one or more entries to the IP routing
table whereby the "gateway" IP address is that of the peer
(or the dummy address as mentioned above).
For example, suppose your ISP is aol.com, and you want to
route all UK-bound IP traffic via them. There is a modem
connected to port 3, and you have created a suitable
connection script named AOL.SCR.
a) You don't know the IP address of AOL's router, so you
choose a dummy address of "10.10.10.10".
b) You then issue the command "DUN ADD 10.10.10.10 AOL.SCR",
or include it in IPROUTE.SYS or BOOTCMDS.SYS.
c) Finally, you add a routing entry as follows:
"IP ROUTE ADD 44.131.0.0/16 10.10.10.10 3 d"
which means "route all 44.131.x.x (UK) traffic via (dummy)
gateway 10.10.10.10 on port 3 (the modem port) using
datagram mode.
Whenever XRouter receives a frame with a destination address
in the 44.131 series, it will now invoke the dial script
AOL.SCR.
DUN Script Commands Overview
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
CONTROL Raise / lower RS232 DTR signal.
MODE Protocol to use upon successful login.
PPP PPP configuration commands.
SEND Send text.
SLEEP Temporary pause.
WAIT Wait for text in received data.
DUN Script Commands In Detail
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
CONTROL - Raise / Lower RS232 DTR signal.
Syntax: C[ontrol] <up | down>
The CONTROL command is used to raise or lower the
RS232 DTR (Data Terminal Ready) line. Most modems
require the DTR signal to be "up", and will disconnect
or reset when it goes down. Those modems which do not
do this by default can usually be configured to do so
by including "&D2" in the initialisation string.
MODE - Set protocol to use upon successful login.
Syntax: M[ode] <kiss | ppp | slip>
Example: MODE PPP
MODE specifies the protocol to use after your system
has logged into the remote host, i.e. when the script
ends without error. It must precede the dialling and
login sequence, and any protocol dependent commands,
such as the PPP commands.
PPP - PPP configuration commands.
Syntax: P[pp] <idle | ipcp | lcp | log | pap> [arg]
Example: PPP IDLE 300
PPP commands are used to configure the PPP subsystem
for the connection being established. Note that
within DUN scripts the <port> argument is omitted
because XRouter knows which port the script is using.
SEND - Send a line of text.
Syntax: S[end] <text>
Example: SEND ATDT01674302153
The SEND command sends one line of text to the modem
or the remote host, for example modem initialisation
and dial commands, or login commands. The <text>
argument may contain spaces, and the system will
append a carriage return/line feed.
SLEEP - Temporary pause.
Syntax: SL[eep] <millisecs>
Example: SLEEP 5000
The SLEEP command causes the script to pause for the
specified interval. For example, you would need a
short delay after issuing a modem reset command
before any more commands would be accepted by the
modem. When the pause is complete, script execution
continues on the next line.
WAIT - Wait for received text.
Syntax: W[ait] <millisecs> <string> [exiterr]
Example: WAIT 5000 Password: exiterr
WAIT makes XRouter wait for specific responses from
the modem or remote host. <millisecs> specifies the
maximum wait interval. <string> specifies the string
of characters (20 chars max, no spaces) to wait for.
When the string is seen in the received data stream,
the next script command is executed.
If "exiterr" is present, the script will abort if the
string is not seen before the interval expires. If
not present, the next script command will be executed
upon timeout.
Dial up networking may be administered "on the fly" using the
DUN command , which is detailed in the sysop command reference
section. The DUN ADD and DUN LOG commands may also be used in
IPROUTE.SYS and / or BOOTCMDS.SYS to configure the system at
boot time.
Example DUN script
~~~~~~~~~~~~~~~~~~
; Xrouter DUN script for establishing PPP connection with ISP
;
; Upon connection, the ISP sends some greetings text, then
; "Login:", and waits for login name.
;
; Upon receiving the login name it sends "Password:" and
; waits for the caller to send the password.
;
; Upon receiving the password, the ISP sends
; "Entering PPP mode".
;
;
; Drop DTR to reset any modem error condition
control down
;
; Wait for 1 sec
sleep 1000
;
; Raise DTR to allow normal operation
control up
;
; Specify the mode to use after link is established
mode ppp
;
; ISP requires PAP authentication: username=gb7pzt,
; password=bsfjflavs
ppp pap user gb7pzt bsfjflavs
;
; Get the modem's attention
send AT
;
; Wait for up to 5 secs for an "OK" response. Abort if none
wait 5000 OK exiterr
;
; Modem is awake. Dial the ISP
send ATDT01905643000
;
; Wait for up to 1 minute for the "user:" login prompt
wait 60000 user exiterr
;
; Prompt obtained. Send username
send gb7pzt
;
; Don't bother waiting for "password:" prompt, just send
; it after 1 sec.
sleep 1000
send bsfjflavs
;
; Wait for confirmation of entry to PPP mode
wait 30000 PPP exiterr
;
; ISP is now in PPP mode. XRouter will enter PPP mode when
; script ends
;
FILES
BOOTCMDS.SYS, IPROUTE.SYS and dialler scripts all reside in
the same director as XRouter.EXE.
CAVEATS
DUN development was halted abruptly before it had been
properly finalised, debugged and documented. You are
therefore urged to use it with caution, and report any bugs.
SEE ALSO
BOOTCMDS.SYS(8) -- Boot Up Commands File
DIAL(1) -- Dialler Commands.
DUN(1) -- Dial-Up Networking.
IPROUTE.SYS(8) -- IP Routing / Configuration File.
PPP(1) -- Point to Point Protocol Commands.
PSTN(9) -- PSTN Modem Support.
DX-SVC
DX-SVC(9) XROUTER REFERENCE MANUAL 22/9/2023
NAME
DX-SVC -- NetRomX DX Service.
DESCRIPTION
The "DX" service uses NetRomX service number 27. It is
normally used by the "DX <nodecall>" function.
It is not intended for direct connection by humans, but such
operation is possible, as described below:
Upon connection to service 27, the user must send a valid
DX command, such as "DX" to show the DX from all ports, or
"DX 16" to restrict the DX list to port 16. Only DX commands
are accepted; any other command will cause disconnection.
The connection is terminated by the server when the transfer
is complete.
It would be possible for automated network crawlers to use
this feature for harvesting DX lists.
SEE ALSO
MH-SVC(9) -- NetRomX MHeard Service.
SERVICES(9) -- NetRomX Standard Services.
DYNDNS
DYNDNS(9) XROUTER REFERENCE MANUAL 6/9/2023
NAME
DYNDNS -- Dynamic DNS Update Client.
DESCRIPTION
More and more people these days have dynamic IP addresses,
i.e. IP addresses which are assigned by their Internet Service
Provider and which may be different each time they log on.
Broadband users are permanently connected to the internet, but
even their IP addresses may be changed at any time by the ISP,
unless they pay extra for a static address.
For the normal internet user this is not a problem, because
no-one else needs to know their IP address. However, if you
want other people to be able to connect to your system, e.g.
if you are running a web server, they need to know your
current IP address. This is where the dynamic DNS providers
come in.
There are many organisations providing dynamic DNS services,
one of whom is DYNDNS.ORG. It is easy, and free, to set up an
account with dyndns.org, and after doing so you may choose one
or more hostnames for your system, for example "g8pzt.ath.cx".
All you then have to do is keep dyndns.org informed of your
current IP address, either manually or using an automatic
update client. Whenever someone asks their system to connect
to "g8pzt.ath.cx", they are given its current IP address.
Xrouter has an integral client for automatically maintaining
dynamic DNS entries at dyndns.org, thus obviating the need to
run an external client or perform manual updates. If the
client is enabled, and your IP address changes, the client
will update one or more hostname entries on the dyndns.org
DNS server. If you do not use dynamic dns, you need read no
further.
The client is enabled by including the directive DYNDNS=1 in
the relevant PORT configuration block in XROUTER.CFG, i.e. the
port which is connected to the Internet. DYNDNS=0 disables the
client, as does omitting the directive altogether. Note: you
must only use this directive on ONE port, and you may crash
XRouter if you try to use it on more than one.
The client requires a configuration file, DYNDNS.CFG, and it
creates a data file DYNDNS.BIN. The configuration file is
heavily commented, so it should be self-explanatory.
If your Xrouter is *directly* connected to the Internet, i.e.
via a PSTN modem or non-routing cable modem, the client simply
monitors the port IP address (which is assigned by the ISP
using IPCP or DHCP), and tells dyndns.org when it changes.
This mode is selected by putting "NO" on the "Use external IP
detection service" configuration line in DYNDNS.CFG.
However, if your connection to the Internet is via a NAT
router such as an ADSL modem/router or Windows ICS, the port
IP address will be a "private" one which no-one else could
access. In this case, the client can be configured to query an
external IP address detection service at regular intervals,
updating dyndns.org if a change is detected. This mode is
selected by putting "YES" on the "Use external IP detection
service" configuration line.
Free accounts on dyndns.org are removed if they haven't been
updated for 35 days. Thus, if your IP address hasn't changed
for 30 days, the client automatically sends an update to keep
the account refreshed.
You may have more than one hostname associated with your IP
address, but that's not a problem. In the "hostname(s) to be
updated" line, simply list the hostname, separated by commas.
Be careful not to include any spaces or mistakes in the line.
FILES
DYNDNS.CFG(8) -- Configuration file
SEE ALSO
DYNDNS(7) -- Enable / Disable Dynamic DNS Update Client.
XROUTER.CFG(8) -- Main Configuration File.
ECHO-SRV
ECHO-SRV(9) XROUTER REFERENCE MANUAL 6/9/2023
NAME
ECHO-SRV -- ECHO Server.
DESCRIPTION
The ECHO server simply echoes back to the user anything that
he sends. This is a useful tool for testing connections,
throughput etc.
The server is accessed by connecting to NetRomX service 7,
or to TCP port 7, or by issuing the ECHO command at
XRouter's command prompt.
An ECHO session can only be ended by sending "/x" or by
disconnection.
The server's TCP port may be changed by using the ECHOPORT
directive in XROUTER.CFG. Setting the port to zero prevents
TCP connections to the server.
SEE ALSO
ECHO(1) -- Start an Echo session.
ECHOPORT(7) -- Specify TCP port for ECHO server
SERVERS(9) -- Servers In XRouter
TCP-PORTS(6) -- TCP Service Ports.
XROUTER.CFG(8) -- Main Configuration File.
ECHO-SRV(9) END OF DOCUMENT
ECHO-SVC
ECHO-SVC(9) XROUTER REFERENCE MANUAL 22/9/2023
NAME
ECHO-SVC -- NetRomX ECHO Service.
DESCRIPTION
NetRomX service 7 is an ECHO server. This simply echoes back
to the user anything that he sends. This is a useful tool
for testing connections, throughput etc.
The session can only be terminated by sending "/x" or by
disconnection.
The server may also be accessed by connecting to TCP port 7,
or by issuing the ECHO command at XRouter's command prompt.
SEE ALSO
ECHO(1) -- Start an Echo session.
ECHOPORT(7) -- Specify TCP port for ECHO server
ECHO-SRV(9) -- About the Echo Server
SERVERS(9) -- Servers In XRouter
TCP-PORTS(6) -- TCP Service Ports.
FING-SRV
FING-SRV(9) XROUTER REFERENCE MANUAL 27/9/2023
NAME
FING-SRV -- FINGER Server.
DESCRIPTION
The FINGER Server allows users to "put a finger on" (i.e.
find information about) other users.
The server is accessed via the FINGER command at the main
prompt, or by connection to TCP port 79. The latter is
intended for use by FINGER clients only.
If the argument to the FINGER command is of the form
<username>, where <username> is usually (but not necessarily)
a callsign, the server looks in the FINGER subdirectory for a
text file of that name. If found it sends the contents to
the user.
If however the argument is of the form <user>@<host>, e.g.
"g8pzt@gb7pzt" the server activates a finger client, which
attempts to establish communication with the Finger server on
the specified <host> to retrieve the desired data.
This server is only partly developed at present, and future
versions may return more information. For the moment, if you
wish to activate this feature, create a FINGER sub-directory
within the XRouter working directory, then simply create a
text file for each user, using the user's callsign or any
other preferred "nickname" as the filename. Use the name
"sysop" for yourself.
The files can contain anything you like, typically the user's
name, location, station details, QSL information etc. You
may wish to ask your users to submit a short summary about
themselves. Please respect people's privacy by including
only the details that they are happy to publish.
As an example, the file finger/g8pzt might contain the text:
Name: Paula
Qth: Kidderminster, Worc's IO82VJ
Age: (withheld ;-)
Other: Sysop G8PZT:KIDDER router, Sysop GB7PZT BBS, Fourpak
Secretary, Unemployed software author with special
interest in comms software. Author of: XServ AX25/IP
BBS, XRouter, XRPi, XS32, Uk White Pages system, PEARL
Off-line reader for Packet Radio, ELINK Echolink
repeater system, Rig control software...
The server is available by default, and requires no setting
up, other than the IP routing and the finger files.
The server's TCP port may be changed, or the server disabled,
by using the FINGERPORT=n directive in XROUTER.CFG. Setting
the port to zero disables the server.
SEE ALSO
FINGER(1) -- Finger Command.
SERVERS(9) -- Servers In XRouter
FINGERPORT(7) -- TCP Port for Finger Server.
TCP-PORTS(6) -- TCP Service Ports.
XROUTER.CFG(8) -- Main Configuration File.
FING-SVC
FING-SVC(9) XROUTER REFERENCE MANUAL 27/9/2023
NAME
FING-SVC -- NetRomX FINGER Service.
DESCRIPTION
NetRomX service 79 is a FINGER server. This server allows
users to "put a finger on" (i.e. find information about)
other users.
The server may also be accessed by connecting to TCP port 79,
or by issuing the FINGER command at XRouter's command prompt.
SEE ALSO
FINGER(1) -- Start a Finger session.
FINGERPORT(7) -- TCP port for Finger server
FING-SRV(9) -- About the Finger Server
SERVERS(9) -- Servers In XRouter
TCP-PORTS(6) -- TCP Service Ports.
FTP-SRV
FTP-SRV(9) XROUTER REFERENCE MANUAL 27/9/2023
NAME
FTP-SRV -- FTP Server.
DESCRIPTION
XRouter's inbuilt FTP sever allows remote sysops to upload,
download, list, rename and delete files, create and remove
directories etc., which is useful when XRouter is located
somewhere inaccessible, such as a garage or remote hilltop.
For example, new configuration and program files may be
uploaded, and the system can then be restarted to perform a
remote upgrade.
The FTP server is only available to sysops. It is protected
by a password grid, and is only accessible to those who have
a password registered in the sysop password file,
PASSWORD.SYS.
Access to all files, drives and directories is unrestricted,
because the FTP server is intended for remote system
maintenance, not as a public file repository. The HTTP and
NFTP servers may be used for that purpose instead.
The FTP server uses standard FTP commands, with the
exception of the USER and PASS login sequence, which are
tailored for use on a radio channel:
In addition to the normal password prompt, the server also
presents the user with a matrix of 5 lines of 5 numbers. The
user may respond either with a string of characters, as with
secure sysop login, or with the full password in plain text.
The grid response would be used on a public RF channel, and
the plain text password on a secure RF channel or wired link.
The server was originally intended for manual operation via
RF links, but automated FTP clients may be used on secure
links, because the password matrix is ignored by all types of
FTP client so far tested. They simply respond with the plain
text password.
There are no automated FTP clients that respond to the
password grid with a secure response, so you cannot (safely)
use them via an unsecured RF link. However, if you leave the
client's password field empty, it will usually prompt you to
enter a password upon connection, at which point you can
respond to the grid challenge.
You are advised not to transfer a password file or any other
sensitive material via insecure RF links.
The directory format is "Windows_NT" because that is the
format which gives the best results with the widest range of
FTP clients.
There is comprehensive help available at the FTP command
prompt, provided you have placed the FTP help files in the
HELP/FTP directory.
The transport mechanism for FTP is TCP/IP, therefore you must
have the appropriate IP routing configured if you wish to use
it via XRouter's IP stack. No configuration (other than some
form of TCP/IP network) is required for operation via the
host system's IP stack.
The TCP port used by the FTP server defaults to the standard,
i.e. 21. This may be changed for XRouter and/or the host
system's TCP/IP stacks using the optional FTPPORT directive
in XROUTER.CFG.
Access to the server may be controlled according to the
client's source IP address, by using appropriate entries in
ACCESS.SYS.
The FTP server commands are described in detail in the sysop
command reference section.
SEE ALSO
ACCESS.SYS(8) -- TCP/IP Access Control File.
AXSCTRL(9) -- TCP/IP Access Control.
FTP-CMDS(1) -- FTP Commands.
FTPPORT(7) -- TCP Port for FTP Server.
TCP-PORTS(6) -- TCP Service Ports.
XROUTER.CFG(8) -- Main Configuration File.
HELP
HELP(9) XROUTER REFERENCE MANUAL 29/12/2023
NAME
HELP -- Help system.
DESCRIPTION
Basic syntax help for most commands is built into XRouter,
and is available using the query (?) command, e.g. "? N"
displays the syntax of the NODES command.
More detailed help is implemented as separate files in the
HELP directory, allowing you to customise it, and add extra
help topics as desired. Each topic occupies a separate file,
with the filename the same as the topic name.
The "H *" command displays a sorted directory of all the
files with the extension ".HLP" (i.e. "topics"). The
extension is not displayed. "H <topic>" displays the contents
of that topic's file. e.g. "H DX" shows help for the DX
command. If the topic is mis-spelled, XRouter lists the
topics with similar names.
The help files don't occupy much space, but you may choose to
omit some or all of them if you are running a system with
limited storage.
In addition to the HELP system, sysops will find more
detailed information in the "sysop manual" using the MAN
command.
FILES
Help files are normal text files, with the extension changed
to ".HLP". They may be created and edited using a simple text
editor such as Notepad (windows) or Leafpad, nano etc (Linux).
All help files are located within the HELP directory, which
itself is in the directory containing XRouter.
English help files should be placed in the HELP directory
itself. Help files for other languages should be placed in
sub-directories of the HELP directory. For example, French
help files should be in HELP/FR/, Spanish help files in
HELP/ES/, German help files in HELP/DE/, and Dutch help files
in HELP/NL/.
Filenames, including the extensions, MUST be in UPPER CASE.
Lower case filenames and files without the .HLP extension are
ignored.
Try to keep the filenames concise, to save excessive typing.
The longer the filename, the more likely that a user will
mis-spell it.
Within the .HLP files, lines beginning with a semicolon ';'
are not displayed to users, so you can use them for comments,
such as file modification details.
Help files can be viewed from the console using <ALT+H>
followed by <H>. This browser window is only around 76
characters wide, so try to keep the lines shorter than this,
to preserve formatting. In any case, lines longer than 72
characters are bad practice, typopgraphically-speaking.
HISTORY
The help system originated long ago on DOS XRouter, and in
those days there was only limited association between filename
extensions and programs. I.e. in most cases, the extension
itself had no real meaning, other than to serve as a reminder
to humans what the file contained. Which is exactly why the
XRouter help files have the extension ".HLP", to distinguish
them from ".MAN" (manual), ".SYS" (system), .CFG
(configuration) and so on. In those days, most programs
could view and edit a text file, no matter what the extension.
Unfortunately, Windows assumes that a file with the extension
".HLP" is a Windows help file, and that ".SYS" is a Windows
system file. If you double click these files, Windows
complains that the format is wrong.
It would be more convenient for *Windows* if the files had
the extension .TXT instead of .HLP, but how would we then know
that they were help files? Therefore, XRouter continues to use
the traditional file names.
SEE ALSO
HELP(1) -- User Help Command.
MAN(1) -- Online Sysop's Manual.
HTTP-PROXY
HTTP-PROXY(9) XROUTER REFERENCE MANUAL 17/10/2023
NAME
HTTP-PROXY -- HTTP Proxy / Tunnel.
DESCRIPTION
HTTP Proxy
~~~~~~~~~~
The HTTP proxy accepts requests on the normal HTTP port and
forwards them to another server.
XRouter (google.com)
.------. .-------. .--------.
| user |-- HTTP --| proxy |-- HTTP --| target |
'------' ^ '-------' ^ '--------'
(GET http://www.google.com/) (GET /)
If a client sends an HTTP request containing an "absolute"
rather than relative URL, e.g. "GET http://www.google.com/",
XRouter's HTTP server recognises that this is not a "local"
request, and opens an HTTP connection to the target server, in
this case www.google.com. It then passes a modified request
and any subsequent HTTP headers to the target server, and
passes any responses back to the client.
Apart from rewriting the request to remove the http:// and
the target hostname, the proxy is fully transparent (a non-
transparent proxy rewrites the request headers).
If the target connection could not be established within a
reasonable time (controlled by PROXYTIMEOUT in HTTP.SYS), an
HTTP error message is returned to the client, and the client
connection is closed.
Downstream Proxy
~~~~~~~~~~~~~~~~
XRouter's HTTP proxy may be configured to pass selected
traffic to a "downstream" proxy. This is enabled by using a
directive with the following format in HTTP.SYS:
PROXY <ipaddr> <port> <subnet_mask>
e.g. "proxy 44.131.91.245 80 255.0.0.0"
<ipaddr> is the IP address of the downstream proxy.
<port> is the TCP port number of the downstream proxy.
<subnet_mask> when combined with the proxy address specifies
the range of addresses which are on the same
subnet as the downstream proxy. These addresses
bypass the downstream proxy, i.e. XRouter will
connect directly to them instead of via the
downstream proxy.
This kludge allows 44-net systems to use a further proxy to
gain a public (Internet) IP address when connecting non-44
websites. This is necessary because 44-net routing is
unreliable at best, i.e. if a 44-net browser tries to
connect directly to Google, the reply probably won't get
routed back.
For example, imagine a mobile station, consisting of a web
browser and XRouter, with an IP/AX25 link to a nearby gateway,
but no Internet connection. The IP address used over the
radio link is 44.131.91.3. The browser has been configured
to use XRouter's HTTP proxy, which means the IP source address
for all HTTP traffic from this station is 44.131.91.3.
192.168.0.1<->192.168.0.2 62.31.206.176 <-> 173.194.41.99
.------. .-------. .-------. .--------.
| user |----| proxy |-- RF Link --| proxy |- Inet-| Google |
'------' '-------' '-------' '--------'
44.131.91.3 <------> 44.131.91.245
(mobile station) (gateway)
Via the nearby gateway, whose IP address is 44.131.91.245,
the mobile station can happily browse 44-net (amprnet)
websites. But when it tries to use Google, the replies
aren't routed back.
However, if the local gateway has been set up with the
above PROXY command, the 44.x.x.x sites are connected directly
by the mobile XRouter's proxy (routed via the gateway), whilst
the non-44 sites are connected via the gateway's HTTP proxy.
At this second proxy, they gain a 62.31.206.176 source
address, which is reliably routable and doesn't rely on the
co-operation of others in the amprnet.
The obvious question is, why not use the gateway's proxy
directly, using NAT to translate the browser's IP address to
44.131.91.3? The answer is that Windows' TCP/IP settings are
tailored for fast wired links and are unsuitable for use via
packet radio. The intermediate (mobile) proxy makes the TCP/IP
radio-friendly.
HTTP Tunnel
~~~~~~~~~~~
The HTTP tunnel allows users located behind a corporate
firewall, which blocks all non-HTTP traffic, to access regular
telnet destinations. A Java client applet, such as XWEB.CLASS
(supplied) would be typically be used to set up the connection
through the tunnel.
.--------. .------. .--------.
| client |-- HTTP --| XRouter |-- Telnet --| target |
'--------' '------' '--------'
All traffic between the Java client and XRouter is carried on a
regular HTTP port 80 connection, which is allowed to pass
unhindered through the corporate firewall.
An HTTP tunnel connection begins like a regular HTTP session,
but instead of the GET method it uses CONNECT. For example:
CONNECT g8pzt.ath.cx:23 HTTP/1.1
Both host and port number must be present in the "URL" portion
of the request. The "host" portion may be either a hostname,
or an IP address in dotted decimal form.
If the request is denied because the destination is blocked by
the security rules, the HTTP error message is "403 Forbidden",
and the session terminates.
If the request is allowed (see "security" below), the server
attempts to connect to the specified host. If successful, it
then sends "200 Connection established" to the client,
followed by a blank line. The session then becomes fully
transparent, and the HTTP server plays no further part in any
transactions. The streams are full 8-bit binary.
Proxy / Tunnel Timeouts
~~~~~~~~~~~~~~~~~~~~~~~
By default, 30 seconds is allowed for name resolution, and
another 30 for the connection to establish. This timeout may
be altered using the PROXYTIMEOUT directive in HTTP.SYS (It
may need to be more than 60 sec via radio channels).
If the connection couldn't be established for any reason, the
server sends a 5xx failure message, and the session terminates.
Proxy / Tunnel Security
~~~~~~~~~~~~~~~~~~~~~~~
If not configured correctly, the HTTP tunnel and proxy could
pose a serious security risk, because they could allow users
to access destinations behind your firewall. In addition,
they could be used to access an external destination via your
IP address, thus hiding the identity of the caller.
Therefore by default the proxy and tunnel are disabled. In
order to enable them you must configure some security...
HTTP.ACL is the Egress Control file, i.e. it controls who the
users of the proxy / tunnel are allowed to connect to. If the
file is not present, or there are no suitable entries in the
file, the tunnel is blocked.
It is suggested that egress control is configured such that
"external" (i.e. Internet) users should only be allowed to
connect to specific "internal" (i.e. intranet) destinations,
such as the TELNET and CHAT servers, whilst intranet users may
be allowed to connect to any destination. See HTTP.ACL for
details.
SEE ALSO
HTTP.ACL(8) -- HTTP Proxy / Tunnel Egress Control File.
HTTP.SYS(8) -- HTTP Proxy / Rewrite Rules.
HTTP-SRV(9) -- HTTP Server.
HTTP-SRV
HTTP-SRV(9) XROUTER REFERENCE MANUAL 27/9/2023
NAME
HTTP-SRV -- HTTP Server.
DESCRIPTION
XRouter's HTTP server delivers HTML files from disk to user,
and also provides an HTML interface to XRouter for users and
for system management. The following functions are provided:
- HTML file server
- Server Side Includes
- Browser interface to XRouter
- URL Rewriting
- Malicious request blocking
- Java applet
- HTTP Proxy
- HTTP Tunnelling
(For details of the proxy / tunnel, please see the manual
section for HTTP-PROXY.)
Connectivity
~~~~~~~~~~~~
By default, the HTTP server uses the standard HTTP port,
which is TCP port 80, and the server is available via both
XRouter and the host system's IP stacks. It is also always
available as NetRomX service 80.
The TCP port number, and availability on each stack, may be
changed by using the HTTPPORT directive in XROUTER.CFG.
Setting the port number to zero disables the server on that
stack. See the HTTPPORT manual page for more information.
Server Root Directory
~~~~~~~~~~~~~~~~~~~~~
The HTTP server's "root" directory is specified using the
HTTPROOT directive in XROUTER.CFG, e.g. "HTTPROOT=C:\WEB".
This allows the HTML files to be located somewhere more
convenient, even on another drive if required.
If you omit this directive, the default will be a directory
called "HTTP" within the XRouter working directory. Users
are not able to "climb out" of that directory, and if they
attempt to do so they are IP-banned indefinitely.
If the directory doesn't exist, the server will not work.
For security reasons it is important that you don't use the
XRouter working directory as the HTTP root!
Default Page
~~~~~~~~~~~~
When servicing a request which doesn't include a filename in
the URL, (e.g. "http://g8pzt.ath.cx/") the server looks in
the HTTP root directory for a file called INDEX.HTM. If that
file is not present, it looks for DEFAULT.HTM. You may
therefore use either file as a "landing page" or an index to
your site.
An example INDEX.HTM is supplied for your guidance. It is by
no means a perfect web page, just something thrown together
to test a concept. You are encouraged to change it to suit
your own preferences. You may need to alter the address in
the "Connect" link to suit your own IP address / hostname.
The connect function is normally performed by a Java applet.
INDEX.HTM is meant as a default entry point for your XRouter
web site. Although XRouter's primary purpose is a router not
a server, and the primary purpose of its HTTP server is to
provide a web interface to the node, you may choose to create
a complex web site, of which the command interface is but a
small part.
You may prefer to use INDEX.HTM as a splash or menu page for
your site, putting the command interface on one or more linked
sub-pages. Or you may choose the opposite approach, putting
all the commands on the main page along with links to other
sites. The creativity is left to you...
Executing XRouter Commands
~~~~~~~~~~~~~~~~~~~~~~~
When the server receives a request whose URL begins with
"/exec?cmd=", e.g. it passes the command to XRouter for
execution, and serves a "template" page displaying the
response to the command. The template serves as a wrapper for
the text.
If the command has arguments, they must be passed as "arg1",
"arg2" etc. using the format "&arg1=x", where 'x' represents
the argument. There must be no spaces in the URL.
Example: "exec?cmd=n&arg1=h" - executes "N H"
If you wish to override the inbuilt html template, edit the
file EXEC.HTM, which was supplied with the installation
package, and put it in the XRouter working directory. This
file does not reside within the HTTP directory tree because
it is not intended to be served in the normal way.
If EXEC.HTM exists, the server will serve it in place of the
inbuilt template, replacing the <TEXT> tag with the result of
the executed command. EXEC.HTM does not currently support
Server Side Includes (see below).
Commands in Forms
~~~~~~~~~~~~~~~~~
Another way of executing XRouter commands is within HTML
forms.
The form tag's ACTION field should be "exec". Within radio
button <INPUT> elements the NAME field should be "cmd" and the
VALUE field should be the command plus any arguments, enclosed
in quotes. Further arguments can be specified with text input
elements, as shown in the following example:
<FORM ACTION="exec">
<INPUT TYPE=radio NAME=cmd VALUE="n v">Via:<BR>
<INPUT TYPE=radio NAME=cmd VALUE="n >">>Qual:<BR>
<INPUT TYPE=radio NAME=cmd VALUE="n <"><Qual:<BR>
<INPUT TYPE=radio NAME=cmd VALUE=n>Routes to:<BR>
<INPUT TYPE=text SIZE=9 NAME=arg1>
<INPUT TYPE=submit VALUE=Go>
</FORM>
Server Side Includes
~~~~~~~~~~~~~~~~~~~~
Server Side Includes (SSI) provide another means to generate
dynamic HTML. Special tags in the HTML files cause the server
to replace the tag with alternative data (such as the contents
of another file) when the file is served.
Server Side Includes are useful for including a common piece
of code throughout a site, such as a page header, a page
footer or a navigation menu. If the common code is modified,
all pages display the new code. This is preferable to having
to modify every page.
SSI has a simple syntax:
<!--#directive parameter=value parameter=value -->
Directives are contained within HTML comments so that if SSI
is not enabled, users will not see the SSI directives on the
page, unless they look at its source.
Note that the syntax does not allow spaces anywhere between
the leading "<" and the directive. The tag must begin with
the exact sequence "<!--#" otherwise it won't be recognised.
The SSI directives currently accepted are as follows:
Directive Parameter Parameter value
~~~~~~~~~ ~~~~~~~~~ ~~~~~~~~~~~~~~~
ECHO VAR DATE_LOCAL
ECHO VAR LAST_MODIFIED
EXEC CMD {any XRouter cmd string}
FLASTMOD FILE {relative filename}
FSIZE FILE {relative filename
INCLUDE FILE {any file under current dir}
INCLUDE VIRTUAL {any file within http tree}
ECHO displays the contents of a specified HTTP environment
variable. Variables include DATE_LOCAL which displays the
local date and time, and LAST_MODIFIED which displays the
modification date and time of the HTML file that is being
served.
Example: <!--#ECHO VAR=DATE_LOCAL -->
EXEC executes a command. The CMD parameter specifies that the
parameter value contains an XRouter command, and the parameter
value specifies the command and any argument(s). If the
command has arguments, the string should be enclosed in
quotes. Not all commands are allowed, only those which are
non-interactive and normally available to users. The results
of the execution are displayed to the user. If the response
contains tables, the whole directive should be enclosed in
<PRE></PRE> tags to preserve the formatting.
Example: <PRE><!--#EXEC CMD="r r" --></PRE>
FLASTMOD and FSIZE display the date when the specified
document was last modified, or the specified document's size.
The FILE or VIRTUAL parameters specify the document to use.
The FILE parameter defines the document as relative to the
current document path; the VIRTUAL parameter defines the
document as relative to the HTTP root.
Example: <!--#FSIZE FILE=myfile.txt -->
INCLUDE allows the content of one document to be included in
another. The file or virtual parameters specify the file
(HTML page, text file, script, etc.) to be included. The FILE
parameter defines the included file as relative to the current
document path; the VIRTUAL parameter defines the included file
as relative to the HTTP root.
Example: <!--#INCLUDE VIRTUAL=/bbs/msglist.txt -->
If the included file also contains Server Side Includes, they
will not be actioned.
Some servers will not execute SSI unless the HTML file has a
.SHTML, .SHTM or .STM extension. XRouter does not require
this.
SSI cannot be used in EXEC.HTM at present.
URL Rewriting
~~~~~~~~~~~~~
URL rewriting modifies the URL's of incoming requests,
according to a set of REWRITE rules in HTTP.SYS. This can be
used to organise widely-dispersed resources into a logical
directory tree.
The resources may be located on the same PC or even on
different servers, but can be made to look as if they are all
in the same tree on your server. This is done by replacing
parts of the requested URL with alternative strings of
characters.
For example, if you only have one public IP address, but you
have more than one HTTP server on your LAN which you wish to
make visible to the outside world, you could use non-standard
port numbers for the additional servers, but that is messy,
(e.g. http://g8pzt.atx.cx:8081). People cannot remember the
port numbers, let alone be bothered to type them in!
This is where XRouter can help, using URL rewriting plus the
HTTP proxy to redirect requests to any number of alternate
servers according to the first part of the URL. E.g. a URL
which begins with "/bbs" could be redirected to the web
server on your BBS.
If the rewritten URL begins with "http://{address}[:port]",
where {address} can be either a hostname or IP address, it is
treated as a proxy request, and redirected to the appropriate
server.
For more information see the manual section on HTTP.SYS.
Malicious Request Blocking
~~~~~~~~~~~~~~~~~~~~~~~~~~
XRouter's HTTP server doesn't suffer from the usual Windows
vulnerabilites, so malicious HTTP requests designed to
exploit them are simply a bandwidth-wasting nuisance
rather than a real threat. You can frustrate the hackers
by deploying the HTTPBAN.SYS file.
This file contains "signatures" or "templates" of typical
malicious request URL's. For example a request for
"default.ida" is part of a Code Red Worm attack, whilst
requests for "cmd.exe" are an attempt to locate vulnerable
Windows servers.
You can find out which are the common hacks by examining your
daily logfiles, looking for the "HR ... " (HttpRequest) lines.
Common ones are "/default.ida" and "/scripts".
The templates are compared in a sliding match with each
requested URL. If any part of the first 256 bytes of the URL
matches a template, the sender's IP address is entered into a
ban list and all further IP datagrams from that host are
ignored until XRouter is restarted. Up to 200 hosts can be
banned simultaneously.
For more information, see the manual section on HTTPBAN.SYS.
Java Applet
~~~~~~~~~~~
The Java applet XWEB.CLASS can be used to connect to XRouter
with a web browser.
The distribution archive contains the applet file, plus 3
rudimentary .HTM pages for you to examine or experiment with.
CONNECT.HTM is the menu page for 3 types of connection, and
would typically be accessed via a "connect" link on the main
page. You may however wish to put the 3 connect options
directly on the main page - it's up to you.
CONN23.HTM uses the Java applet to perform a normal telnet
connect to port 23. The port number is configurable (see
below), so you could clone the page for use with your chat
server.
CONN80.HTM uses the Java applet to perform a "tunnelled"
connection, which can be used via corporate firewalls which
block normal Telnet.
If you wish to use the above files and the applet, they
must be located within the HTTP tree.
You can change the applet colours and font, the number of rows
and columns displayed, and the connection mode (normal TELNET,
or HTTP tunnel), using <PARAM> tags in the HTML file. For
example: <PARAM NAME="font" VALUE="Courier">.
The parameters which can be specified are as follows:
Param name Default Description
-----------------------------------------------------------
rows 22 No. of rows in text window
cols 80 No. of columns in text window
bgcolour Dark grey Applet background colour.
borderColour Light grey Applet framework colour.
textBackground Black Background for text/cmd windows.
textColour White Colour of sent / rcvd text.
font Times Font style for sent / rcvd text
port 9999 TCP port number for connections.
mode Normal Connection mode (normal / proxy).
The only mandatory parameter is "port". This should normally
be 23 for a normal telnet connect or 80 for an http-tunnelled
connect, but you may use other values if you have moved or
translated your Telnet or HTTP ports.
Colours should be specified as a 24 bit hexadecimal number in
'C' style, e.g. 0xEECCFF, where the first 2 digits represent
the RED value, the second two digits represent the GREEN value
and the last two digits represent the BLUE value. Some
browsers can only display 216 discrete colours, so you should
preferably use the "browser-safe" values, which are all formed
from combinations of 00, 33, 66, 99, CC and FF.
The default font is quite small, and the characters are not of
a constant width, which means tables sent by XRouter will not
line up correctly. You may use the "font" parameter to
override the default. The recommended font is "Courier",
which is slightly larger and uses constant width characters.
Note: if the chosen font is not found on the client's device,
their default font will be used, so stick to the common ones.
You may need to reduce the number of rows or columns displayed
by the applet if you find it won't fit on a 640*480 screen. It
fits nicely on 800*600, but you may wish to optimise it for
another screen size, or even offer users the choice.
If you change the font, rows or cols, you may need to tweak
the WIDTH and HEIGHT attributes in the APPLET tag to prevent
parts of the applet from being obscured.
FILES
In XRouter root: EXEC.HTM, HTTP.SYS, HTTPBAN.SYS
In HTTP tree: INDEX.HTM, CONNECT.HTM, CONN23.HTM, CONN80.HTM,
XWEB.CLASS
SEE ALSO
HTTP.ACL(8) -- HTTP Proxy / Tunnel Egress Control File.
HTTP.SYS(8) -- HTTP Rewrite / Proxy Control File.
HTTP-PROXY(9) -- HTTP Proxy / Tunnel
HTTPBAN.SYS(8) -- HTTP URL Blocking File.
HTTP-SVC(9) -- NetRomX HTTP Service
HTTPPORT(7) -- TCP Port for HTTP Server.
TCP-PORTS(6) -- TCP Service Ports.
XROUTER.CFG(8) -- Main Configuration File.
HTTP-SVC
HTTP-SVC(9) XROUTER REFERENCE MANUAL 7/9/2023
NAME
HTTP-SVC -- NetRomX HTTP Service
DESCRIPTION
NetRomX Service 80 accesses XRLin's HTTP server, allowing
HTTP over Netrom.
HTTP over NetRom? Shock horror! What a phenomenally stupid
idea!!! Well maybe it is, maybe not? It's just another
communication tool.
This service is not new - it has been in XRouter since Jan
2013. If you access an XRouter's web interface via TCP/IP,
it's what allows you to click on certain nodes in the nodes
list, and go to their default pages.
Yes it might be slow, but if the HTML is kept clean and tight,
it is workable, and unlike the Internet, the addresses are
consistent. A node's "NetromWeb" address is simply its
callsign.
The service number is not affected by the setting of HTTPPORT,
which only affects TCP/IP access to the server.
SEE ALSO
HTTP-SRV(9) -- HTTP Server
SMS-SVC(9) -- Short Messaging Service.
SERVICES(9) -- NetRomX Standard Services.
IDS
IDS(9) XROUTER REFERENCE MANUAL 20/10/2023
NAME
IDS -- Intrusion Detection System.
DESCRIPTION
The purpose of XRouter's Intrusion Detection System (IDS) is
to detect, repel and warn the sysop of, suspicious or
malicious activities.
It mainly operates on IP, where most of the threats arise,
but also watches AX25 / Netrom. It does not need any setup
and should not interfere with normal operation.
The main indication of its presence is the "Security Monitor"
window, which displays any detected threats. Other than that,
there might be the occasional warning on the bottom right of
the "overview" window.
Security Monitor Window
~~~~~~~~~~~~~~~~~~~~~~~
Positioned between the "Overview" window and the "Consoles",
the "Security Monitor" is intended to remind / inform you of
any suspicious actitvity.
In most cases, this is just a waste of a window, showing all
zeros and mostly empty space. That's a good thing - it shows
you are (probably) safe.
However if you have any IP services enabled, the window might
come alive with activity. The top section shows an overview
of the threat statistics, whilst the rest of the window shows
the latest warning messages, in various colours according to
the severity of the threat.
There are 4 notification Levels as follows:
1 - IMPORTANT!: Intrusion / Escalation attempts (cerise)
2 - WARNING: Recon attempts (port scans etc (red)
3 - ADVISORY: Possible suspicious events (yellow)
4 - INFORMATIVE: Unusual events (white)
You can change which notifications are displayed using the
following command:
IDS V[erbosity] [level]
[level] is 0 (no notifications) to 4 (all notifications).
For example the command "IDS V 2" enables intrusion and recon
notifications only.
Pressing <F1> on the IDS window displays a pop-up box with
the notification levels, a brief description of the stats,
and a reminder of the IDS commands.
The various statistics displayed in the upper pane are
described in the section "IDS Statistics" below.
IDS Logging
~~~~~~~~~~~
The IDS notifications pane only has limited space, and you
can't watch it all the time, which is where IDS logging comes
in handy.
IDS events can be logged, either by enabling the IDS option
in the LOG directive, or by using the command "IDS LOG ON".
if IDS logging is enabled, some (but not all) IDS events are
logged to the file LOG/YYMMDD_IDS.LOG, where YYMMDD are the
2 digit year, month and day of the month.
Log entries are usually of the form:
<time> <source_IP> -> <dest_IP>[:port] <description>
For example:
15:11:12 192.168.0.135 -> 192.168.0.101:137 Unsolicited UDP
20:16:02 192.168.0.135 -> 192.168.0.101:443 TCP SYN - refused
21:04:57 44.197.188.109 -> 44.135.49.90:443 TCP SYN - refused
The last entry reveals a threat from the section of 44-net
that was sold off to commercial interests, and the need to
update the IP access Control List entries to block this
section of the 44/8 address space.
IP Banning
~~~~~~~~~~
One part of XRouter's defences is "IP banning".
If XRouter detects malicious activity on its own TCP/IP
stack, it will "ban" the originator's IP address. This means
that any further packets from that IP address are ignored,
for as long as the ban lasts.
If malicious activity is detected on any Linux TCP or UDP
port that is currently used by XRouter, that also causes
a ban. In this case, TCP connections are terminated, and any
further connections or UDP frames are ignored.
There is no time limit on IP bans, and they are preserved
across reboots. Up to 200 IP addresses can be banned at once.
A larger table would become unwieldy, so when a new address
is added, the oldest one is dropped. In practice this isn't
usually a problem because the oldest aggressor has usually
given up long ago, and is unlikely to come back.
IP bans can be added manually using the IP BAN ADD command,
the format of which is:
IP B[an] A[dd] <ipaddr> [netmask]
For example:
ip ban add 44.197.188.109
ip ban add 44.128.0.0 255.192.0.0
They can also be removed using "IP U[nban] <ipaddr>".
The ban list can be displayed using "IP B[an] L[ist]"
Port Scanners
~~~~~~~~~~~~~
Scans are not necessarily dangerous, although in some cases
they may consume substantial resources. The main issue with
scans is that are usually a prelude to an attack. Once your
presence has been detected by a scan, the hackbots tend to
inform each other and launch an attack. It may not happen
immediately, but it will usually happen.
If you have any TCP/IP services open to the Internet, for
example Telnet or even AXUDP, scans are inevitable. The IDS
warns you, so you can take evasive action, such as IP and
TCP / UDP ingress filtering, and allows you to test its
efficacy. It also disrupts the scanning process, causing the
hackbots to time out and move on.
A word of warning: If you scan your own system, you might
suddenly find that you can no longer access XRouter from
the machine that performed the scan because its IP has been
banned. If you can access XRouter from its own console, or
via a machine that hasn't been IP-banned, you can use the IP
UNBAN command to remove the banned address.
Honeypots
~~~~~~~~~
In this context, a honeypot a sticky trap, set up on popular
TCP or UDP ports, for catching internet low-life.
Hackbots generally start their attacks by probing for open
TCP ports, and to save time they often start with the most
popular ones - telnet, SSH, HTTP, VNC and so on. If they find
an open port, they tend to inform each other, then they all
concentrate their attacks on that port.
Unless you have a particular service port open, the chances
are that anyone who tries to connect to it is up to no good.
So the honeypot is a mitigation measure. It LOOKS like an
attractive open port, but it's not! Anyone who connects to it
gets their IP address logged and banned. After that they
can't do any more attacking unless they change their IP
address.
It's not foolproof. Nation states have access to large
numbers of IP addresses. But IP banning slows them down,
and the IDS alerts you that there is a problem.
Setting Up a Honeypot
~~~~~~~~~~~~~~~~~~~~~
IP sub-commands BAN PORT ADD, BAN PORT DROP, BAN PORT LIST,
and BAN PORT SAVE allow management of the "honeypot" ports.
A honeypot is created using the following command:
IP B[an] P[ort] A[dd] <TCP|UDP|ALL> <start> [end]
<TCP|UDP|ALL> - protocol(s) to catch.
<start> - single port, or the start of a range.
[end] - last port in a range.
For example: "ip ban port add tcp 443" sets up a honeypot
which IP bans anyone who tries to cpnnect to TCP port 443.
Similarly "ip ban port add tcp 5900 5999" creates a honeypot
covering the TCP port range commonly probed for VNC.
Honeypots and their stats can be displayed using:
IP B[an] P[ort] L[ist]
They can be saved (to IPBAN.SYS) using:
IP B[an] P[ort] S[ave]
And they can be removed using:
IP B[an] P[ort] D[rop] <TCP|UDP|ALL> <start> <end>
Note that both the start and end ports are mandatory in the
DROP command. For single ports, both numbers are the same.
IDS Statistics
~~~~~~~~~~~~~~
If you have access to XRouter's display, the top section of
the "Security Monitor" window gives you some statistics.
If you have "sysop" access to XRouter you can also view more
comprehensive stats using either the "S[tats] IDS" or the
"IDS S[tats]" commands, both of which display the same data,
something like this:
IDS Events: 25778 Cmd Overflow: 0
FTP DIR Hacks: 0 IP Addr Heard: 100
IP Addr Banned: 200 IP Banned Total: 183
IP Dgram Blocked: 2076 ICMP Frm Blocked: 32
Honeypot Hits: 0 UDP Segs Ignored: 3251968
UDP Segs Blocked: 22 TCP Segs Ignored: 9967
TCP Segs Blocked: 2022 TCP Conn Blocked: 763
Bogus SYNs: 15776 Smurf Attacks: 0
Fraggle Attacks: 0 IP Frag Attacks: 0
(Tiny=0 Huge=0 Overlapped=0)
TCP Scans: SYN=1 FIN=0 ACK=57 NUL=0 MAI=82 XMS=0 OTH=9600
Rejected Logins: 763 (Telnet=763, Rlogin=0, FTP=0,
TelProxy=0)
Malicious Logins: 182 (Telnet=182, Rlogin=0, FTP=0,
TelProxy=0)
HTTP No-Request: 0 HTTP Bad Request: 0
HTTP Blocked: 0
"IDS Events" is the total number of times the IDS has noticed
something suspicious.
"Cmd Overflow" is the number of times that someone has
attempted a buffer overflow attack.
"FTP DIR Hacks" is the number of attempts to escape from the
FTP root directory.
"IP Addr Heard" is the number of unique IP addresses heard.
"IP Addr Banned" is the number of IP addresses in the "banned
IP" table. As the table is saved across reboots, it
is normal for it to be full.
"IP Banned Total" is the number of new IP addresses banned
since bootup. This figure may exceed the table size
because new bans replace stale ones.
"IP Dgram Blocked" is the number of IP datagrams blocked
because the sender's IP address was in the banned IP
table.
"ICMP Frm Blocked" is the number of ICMP frames blocked
because the sender's IP address was in the banned IP
table.
"Honeypot Hits" is the number of times someone attempted to
access one of the "honeypot" ports. These are traps
which lure port scanners into an IP ban.
"UDP Segs Ignored" is the number of UDP segments ignored
because there was no matching socket to receive them.
"UDP Segs Blocked" is the number of UDP segments blocked
because the sender's IP address was on the banned IP
list.
"TCP Segs Ignored" is the number of TP segments ignored
because there was no matching listener socket.
"TCP Conn Blocked" is the number of TCP connection attempts
blocked because the sender was on the banned IP list.
"Bogus SYNs" is the number of TCP connection attempts blocked
because the SYN was malformed or maliciously crafted.
"Smurf Attacks" are distributed denial of service attacks
which use ICMP directed at broadcast addresses.
"Fraggle Attacks" are variations of Smurf attacks, where the
attacker sends lots of traffic to UDP ports 7 (Echo)
and 19 (CHARGEN)
"IP Frag Attacks" is the number of IP fragmentation attacks.
These attacks attempt to overwhelm or crash the IP
fragment reassembly mechanism.
Tiny - First fragment is too short to contain valid
TCP+IP headers, so it could bypass port-number
filtering.
Huge - Fragment exceeds maximum datagram size.
Overlapped - Fragments which overlap but don't align.
"TCP Scans" is the number of TCP port scans detected and
blocked. Totals for each scan type are shown
separately:
SYN - Scanner sends SYN but never completes the 3 way
TCP handshake.
FIN - TCP segments with only the FIN bit
ACK - Only the ACK flag is set
NUL - NULL scan (no flags are set)
MAI - Maimon scan (FIN and ACK flags set)
XMS - Xmas Tree scan (FIN, PSH and URG flags set)
OTH - Other types of scan
"Rejected Logins" are Telnet / FTP etc logins which were
rejected because the source IP was banned or the
login credentials were incorrect.
"Malicious Logins" are TCP logins attempted using suspicious
or common attack credentials.
"HTTP No-Request" is the number of connections to XRouter's
HTTP server which didn't contain an HTTP request.
These are usually the result of port scanning.
"HTTP Bad Request" is the number of malformed or maliciously
crafted HTTP requests. These are usually attempts to
exploit vulnerabilities in certain types of HTTP
server or operating system.
"HTTP Blocked" is the number of HTTP server connections
refused because the sender's IP was in the blocked
IP list.
IDS-Related Commands
~~~~~~~~~~~~~~~~~~~~
IDS L[og] [on | off]
IDS S[tats]
IDS V[erbosity] [0-4]
IP B[an] A[dd] <ipaddr> [netmask]
IP B[an] D[rop] <ipaddr>
IP B[an] L[ist]
IP B[an] P[ort] A[dd] <TCP|UDP|ALL> <start> [end]
IP B[an] P[ort] D[rop] <TCP|UDP|ALL> <start> <end>
IP B[an] P[ort] L[ist]
IP B[an] P[ort] S[ave]
IP B[an] S[ave]
IP Q[uiet] [level]
IP U[nban] <ipaddr>
S[tats] IDS
CAVEATS
The IDS is not set in stone. It evolves and morphs as the
threatscape changes. Therefore some of the above may be out
of date already.
Nor does it claim to be a 100% foolproof system. XRouter's
primary purpose is for Amateur Packet Radio, not Internet
defence! The IDS must strike a balance between defending the
system, informing (but not overwhelming) the sysop, and not
getting in the way of normal operations.
SEE ALSO
IDS(1) -- Intrusion Detection System Commands.
IP(1) -- IP-related Commands.
ACL(1) -- IP Access Control List Commands.
LOG(7) -- Activity logging options
ACCESS.SYS(8) -- Telnet Access Control File.
IPBAN.SYS(8) -- Banned IP addresses File.
XROUTER.CFG(8) -- Main Configuration File.
AXSCTRL(9) -- TCP/IP Access Control.
IGATE
IGATE(9) XROUTER REFERENCE MANUAL 16/10/2023
NAME
IGATE -- APRS Internet Gateway.
DESCRIPTION
XRouter has an inbuilt APRS Igate, which allows received APRS
packets to be gated to an Internet APRS server, and packets
from the server to be gated to RF. You will need an APRS port
and an internet connection to take advantage of this.
Igate operation is controlled mainly by configuration settings
in file IGATE.CFG. If the file isn't present, the igate
daemon can be started, but nothing will happen. The file
includes keywords which specify the Internet APRS server
addresses, various timers controlling connections, the
filtering rules for gating packets, and the logging options.
In addition to the settings in IGATE.CFG there are a few in
XROUTER.CFG, which control whether or not the Igate daemon
starts at boot-up, and which ports may send to and receive
from the Internet.
Choosing and specifying Internet Servers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The choice of server, and the TCP port to use on that server,
depends on where in the world you are located, and what sort
of data you're interested in. There are several types of
server, and the services they provide aren't always
comparable.
Some servers provide a "raw" data feed containing APRS
activity from all over the world, which can amount to a
considerable volume. Some also provide "filtered" or "local"
feeds, e.g. Ohio-only or messages-only.
There's no point in connecting to a "raw" feed if there is a
"local" feed available, as you will merely be wasting CPU
time and internet bandwidth downloading data you are going to
discard. APRS message-only feeds tend to be on port 1314,
whereas "raw" feeds tend to be on port 10151, or 2023 if
it's a Ahub server.
Using a browser to connect to http://server_address:14501
sometimes produces a status page containing useful server
addresses. You could start your search at "first.aprs.net".
In IGATE.CFG you may specify as many servers as you wish, each
on a separate line with the following format:
SERVER <ipaddress | hostname>:<port>
e.g. SERVER 128.196.58.1:1314
The port number must be separated from the IP address or
hostname by a colon so that the combined address:port forms a
contiguous string of characters with no spaces.
The servers are tried in rotation, starting with the first on
the list. If a connection attempt fails, or the link
subsequently closes, the next server is tried. When the end
of the list is reached it starts all over again at the first
one. The behaviour is modified by various timer settings
- see below.
You may find out which server is currently in use by using the
"TCP STATUS" command.
Connection Timers
~~~~~~~~~~~~~~~~~
There are various keywords which may be used in IGATE.CFG to
control the timings associated with connections to the
Internet servers, and they are as follows:
WAIT <secs> -- Time to wait for connection establishment.
Specifies the number of seconds to wait for connection
after sending a connect request. If not specified, the
default is 60.
If you have a permanent Internet connection, you may wish
to set a lower value, but if you're using dialup you may
wish to make it longer, e.g. 90 secs to allow time for
dialling and modem negotiation. If no response is
received from the server within the WAIT interval, the
next server in the SERVER list will be tried.
PAUSE <secs> -- Interval between successive tries.
Specifies the number of seconds to wait between successive
connection attempts to the same server. Default is 60
secs.
If a server goes down or fails to respond, there's no
point in aggressively trying to connect. For one thing,
if you have connection logging enabled you will build a
big logfile! This timer is mainly of use when you have
only one server in you SERVERS list, or when several
servers go down.
MAXTRIES <n> -- No. of failed connect attempts allowed.
If a server consistently fails to respond to connect
attempts, there's a good chance it has gone temporarily or
permanently off line. The MAXTRIES value specifies the
maximum number of failed connect attempts allowed before a
server is ignored, and the default is 10. If the limit is
reached, that particular server will not be retried until
the SKIP interval (see below) expires.
SKIP <secs> -- "Blacklist" interval.
Specifies the amount of time for which a server will not
be tried after MAXTRIES failed connect attempts. This
effectively removes a server from the list for the SKIP
interval, after which it is placed back on the list.
Default is 3600 secs (1 hour).
Packet Filtering
~~~~~~~~~~~~~~~~
The Igate contains powerful packet filters, which can be
applied to traffic gated in both directions. The filtering
rules are specified in IGATE.CFG using IFILTER (internet to
packet) and PFILTER (Packet to internet) statements, the
general form of which are as follows:
xFILTER <from_call> <to_call> <text>
Each field may include the following wildcards:
* Matches zero or more characters.
? Matches any single character.
# Matches a single digit.
@ Matches a single alphabetic character.
\ Escape - interpret next character literally.
The '*' character may only be used at the end of a field.
For example: "IFILTER G#@@@* * :*" will accept from the
internet feed only those packets sent by valid G0 to G9 + 3
letter callsigns, addressed to anyone, which contain APRS
messages.
The '\' (escape) character causes the next character to be
interpreted literally, instead of as a wildcard, e.g. "\*"
will match '*' and "\\" will match '\'.
A caret '^' at the start of any field will invert the sense of
the whole test, causing matching packets to be REJECTED, e.g.
IFILTER ^M7ABC * *
IFILTER * ^APZ244* !*
The first statement will reject all packets from M7ABC, and
the second will reject all static position reports sent to the
destination APZ244 (e.g. if they can't be trusted). Rejection
statements MUST be placed at the beginning of the filter
rules, before any catch-alls.
The maximum length of each field (pattern) is currently 10
characters. There is no limit to the number of xFILTER
statements you may specify. If no rules are specified,
nothing will be gated.
All valid APRS and UI-View packets (except 3rd party packets,
and those with NOGATE or RFONLY somewhere in the digi path)
received by the router are offered to the PFILTER, providing
the appropriate DIGIFLAGS are set (see below). Mic-E packets
are decoded to text before being offered to the Internet
servers because they may contain characters which won't pass
through the servers. This decoding takes place before
filtering.
You should be VERY careful when designing your filter rules,
as you could quite easily overload the RF channel by
attempting to gate too much data to it. There is little point
in gating non-local data.
To reduce unnecessary traffic, APRS "messages" are only gated
to RF if the recipient has been seen locally on RF within the
last hour.
Radius of Interest
~~~~~~~~~~~~~~~~~~
In IGATE.CFG the statement "RADIUS <km>" sets a radius in
Kilometres from XRouter's position. Position reports from
within this radius are gated to RF, providing they pass the
IFILTER rules. The default radius is 100Km. Setting
"RADIUS 0" allows unlimited gating of positions.
Controlling gating direction / port(s)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Regardless of any other settings, an XRouter port will not
broadcast packets received from the Internet, or offer
received packets to the internet, unless the appropriate bits
are set in the port DIGIFLAG. You should add one or both of
the following values to DIGIFLAG:
Bit Value Option
------------------------------------------------
6 64 Enable gating from Packet to Internet.
7 128 Enable gating from Internet to Packet.
Packets accepted (i.e. passing IFILTER) from the Internet are
broadcast on ALL ports which have bit 7 of DIGIFLAG set, so be
careful not to lazily set DIGIFLAG to 255!
Activity logging
~~~~~~~~~~~~~~~~
Igate activity can be recorded in the file ./LOG/IGATE.LOG by
including a LOG keyword with non zero argument in IGATE.CFG.
The argument is a number made up as follows:
Bit Value Option
------------------------------------------------
0 1 Record Igate daemon start and stop events.
1 2 Record Inet server connections / disconnections.
2 4 Record frames sent from Internet to Packet.
3 8 Record frames sent from Packet to Internet.
The "record frames" options can generate a lot of data, so
they're intended mainly for testing purposes, e.g. making sure
your filters are correctly set. To avoid the logfile growing
too big, you are advised to periodically rename or otherwise
remove it, allowing a fresh one to start.
Starting and stopping the Igate daemon
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The daemon may be started and stopped at any time with the
commands "START IGATE" and "STOP IGATE". If the daemon is
already running, attempting to restart it will simply produce
an error message, as will trying to stop it if already
stopped.
The IGATE.CFG file is re-read each time the daemon is started,
so the configuration can be changed without stopping XRouter,
by editing the file (using Notepad or the PZTDOS line editor),
then re-starting the daemon. Editing can take place while
the daemon is running.
The daemon may be started automatically when XRouter boots, by
including IGATE=1 in the "global" section of XROUTER.CFG.
SEE ALSO
APRS(9) -- Automatic Packet Reporting System.
DIGIFLAG(1) -- Display / Set digipeat options.
EDIT(3) -- PZTDOS Line Editor.
IGATE.CFG(8) -- IGATE Configuration File.
START(1) -- Start Daemon Processes.
STOP(1) -- List / Stop Daemon Processes.
TCP(1) -- TCP status / configuration commands.
XROUTER.CFG(8) -- Main Configuration File.
INFO
INFO(9) XROUTER REFERENCE MANUAL 21/10/2023
NAME
INFO -- Info System.
DESCRIPTION
When the user issues the "I" command without any arguments,
the text specified by INFOMSG (in XROUTER.CFG) is sent to
him.
However, this command may also form the entry point for a
much more comprehensive information system which the sysop
may configure how he wishes. For example you may wish to
include details of the local packet network and clubs, and
maybe a set of tutorials on general packet topics...
In order to do this, the INFO directory must exist (within
the directory containing XRouter), and must contain the
desired info in the form of text files with the extension
".INF".
After using "I" by itself, the user will then be invited to
enter "I *" to list the available info topics. If the user
enters that command, the filenames (without the .INF) are
displayed in alphabetical order, and the user is invited to
read the files using the "I <topic>" form of the command.
If the user enters a filename which is not found,
XRouter displays a list of similar filenames.
The filename should be relevant to the contents, but try to
keep it fairly short. You should aim to keep each file
concise in order to save air time, preferably breaking
complex subjects into a series of small files with "see also"
references to link them. It is very frustrating for users to
begin reading a file only to discover it's not of interest,
and then having to wait a long time for it to finish! You
may use ANSI or HTML in the files, but not pure binary.
Within the .INF files, lines beginning with a semicolon ';'
are not displayed to users, so you can use them for comments,
such as file modification and version details.
SEE ALSO
HELP(9) -- Help System
INFO-SVC(9) -- NetRomX Information Service
INFO-SVC
INFO-SVC(9) XROUTER REFERENCE MANUAL 7/9/2023
NAME
INFO-SVC -- NetRomX Information Service
DESCRIPTION
Isn't it frustrating to connect to a node, only to find that
there is no INFO command, or the sysop hasn't bothered to set
up any information?
Where in the world is it? We aren't all familiar with country
prefixes!
What software is it running? That affects which commands we
must use to find information. What sort of node is it? Just a
router, or is it the node underlying a BBS or DX cluster?
Where can I find more information about the system, the
person or group responsible, the software etc?
The NetRomX "Information Service" (service no. 1) is intended
to answer some of your questions. It is accessed by
connecting to service 1 on any XRouter running version 501v
or later. For example, to connect to G8PZT's info service:
C G8PZT 1
The information is provided in a form which is readable by
both humans and machines. It is of the "<keyword>: <value>"
form, with each piece of information on a separate line.
Every keyword is unique. Only a few have been implemented so
far, although others are planned. Your suggestions would be
welcome.
The server closes the connection after sending the data.
The INFO command accomodates this feature, so the user
doesn't even have to remember the service number or add the
"stay" flag. The syntax is:
I[nfo] [nodecall | nodealias]
Here's a typical session:
info kidder
VK2DOT-1:DOTXR} Info:
Trying G8PZT::1...
VK2DOT-1:DOTXR} Connected to G8PZT::1
Node-Type: Host / Router
Node-Callsign: G8PZT
Node-Alias: KIDDER
QTH: Kidderminster, Worc's
Maidenhead: IO82VJ
Position: 52.400002 / -2.250000
Sysop-Callsign: (to be done)
Software-Type: AX25+NetRom+IP Router/Node
Software-Name: XrPi
Software-Version: 501y (19/7/20)
Software-Author: Paula G8PZT
Software-Info: http://vk2dot.dyndns.org/xrpi
Software-Uptime: 4d, 11h, 3m, 58s
Local-Time: Fri, 21 May 2021 03:27:06 +0000
Local-Sunrise: 05:05
Local-Sunset: 21:08
Netrom-Known: 250
Netrom-Neighbours: 6
AX25-Links: 6
Amprnet-IP: 44.136.16.6
Amprnet-Name: g8pzt.ampr.org
Netrom-Services: 1,2,7,8,9,13,14,16,18,19,21,23,80,87
VK2DOT-1:DOTXR} Welcome back
SEE ALSO
INFO(1) -- Display information.
INFO(9) -- Info system.
SERVICES(9) -- NetRomX Standard Services.
INP3
INP3(9) XROUTER REFERENCE MANUAL 17/10/2023
NAME
INP3 -- Inter-Node Protocol 3.
DESCRIPTION
INP3 is version 3 of the so-called "Internode Protocol". This
is a protocol for exchanging time-based routing information
between neighbour nodes. Despite the misleading name, it is
not concerned with general inter-node traffic, only the
routing information.
INP3 is analogous to NetRom nodes broadcasts, except that the
information is "unicast" to each neighbour via the normal
AX25L2 inter-node links, instead of being broadcast via UI
frames.
NetRom nodes broadcasts and INP3 can happily co-exist on the
same network, as they are are concerned with different
metrics. NetRom broadcasts propogate route QUALITY, whilst
INP3 unicasts propogate TRIP TIME. These are two completely
different metrics, and there is NO valid way to convert one to
the other, especially quality to time, since route quality is
such a nebulous and subjective quantity.
However, there is one caveat: Some types of node software,
including Linux and (X)net (no relation to XRouter!) convert
time to quality and vice versa. This causes distorted routing
when qualities are converted to bogus trip times. Assigning
slightly lower route qualities to these neighbours helps to
prevent traffic being diverted through them.
The protocol is summarised below:
Information Exchange
~~~~~~~~~~~~~~~~~~~~
All INP3 routing information traffic between two neighbour
nodes is carried alongside regular inter-node traffic, by
AX25L2 numbered information frames with PID 0xCF (NetRom).
Link Quality Estimation
~~~~~~~~~~~~~~~~~~~~~~~
The "quality" of an inter-node link is determined by its mean
one-way frame transport time, usually measured by the exchange
of L3RTT frames. This value is called the Smoothed Neighbour
Transport Time (SNTT).
Trip Time
~~~~~~~~~
This is the all-important metric. For a given target node, it
is simply the sum of all the intermediate nodes' SNTTs. It is
measured in 10ms units, with a maximum (horizon) value of
60000, i.e. 600 seconds. A trip time of 60000 is used to mark
a route as unusable.
The sysop may set a local limit which is less than 60000 using
MAXTT. Routes which exceed the local limit are propogated
with the horizon value.
In this context "route" means a path through the network,
involving one or more intermediate nodes. The optimum route
to a target node is generally considered to be the one with
the lowest trip time.
Hop Count
~~~~~~~~~
Each inter-node link is counted as one HOP. This is a second
metric which is propogated alongside trip time. Routes with
lower hop counts are preferred. A hop count of 30 is
considered to be the horizon, and marks the route as unusable.
The sysop may set a local limit which is less than 30 using
MAXHOPS. Routes which exceed the local limit are propogated
with the horizon value.
Propogation of Routing Information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A route via a neighbour is valid as long as it is regularly
updated in unicasts from that neighbor, with a trip time less
than the horizon. If the route is not regularly updated, or
the trip time reaches the horizon, that route is marked as
unusable. If the link with the neighbour is broken, all
routes via that neighbour are marked as unusable.
Routes with trip time below the horizon are called positive
information and represent available nodes. Positive
information is not time critical and, like NetRom nodes
broadcasts, is sent at scheduled intervals only.
Any update of positive information with a slower target time
(or route loss) is called negative information. This is
always propogated immediately.
Information about nodes which are routed via a neighbour is
never returned to that neighbour. Instead it is returned with
horizon values. This is called "poisoned reverse".
Packet Structure
~~~~~~~~~~~~~~~~
Routing information is exchanged using "Routing Information
Frames" (RIF), containing one or more Routing Information
Packet" (RIP). Each RIP contains information about one node,
such as callsign, trip time and hop count, plus optional
fields such as alias and IP address.
A RIF starts with a single identification byte of 0xFF. This
value is guaranteed not to appear in normal L3 frame headers
as the first byte. The end of the RIF is marked by a zero
byte, 0x00. The following diagram shows a RIF containing
one RIP:
Byt: 1 7 1 2 n 1
.------.----------.--------.-------------.-----------.------.
| 0xFF | <axcall> | <hops> | <trip time> | <options> | 0x00 |
'------'----------'--------'-------------'-----------'------'
<------ Routing Information Packet --------->
<-------------- Routing Information Frame ---------------->
<axcall> Callsign in AX25 format
<hops> No. of hops to target (1-30)
<trip time> Trip time to target in 10ms units (1-60000)
<options> Variable length options field as below:
Bytes: 1 1 n = <length>
.----------.--------.--------------.
| <length> | <type> | <data> |
'----------'--------'--------------'
<length> Length of data field in bytes (0-255)
<type> Type of data field (0=alias, 1=IP addr)
<data> Data field.
SEE ALSO
L3RTT(9) -- Layer 3 Round Trip Time
MAXHOPS(7) -- Maximum Hop Count.
MAXTT(7) -- Maximum Trip Time.
QUALITY(1) -- NetRom Route Quality.
ROUTES(1) -- Add, Drop & List Neighbour Routes.
IP-CODES
IP-CODES(9) XROUTER REFERENCE MANUAL 17/10/2023
NAME
IP-CODES -- IP Country Codes.
SYNOPSIS
List of Amprnet region codes.
DESCRIPTION
Within Amprnet, the second octet from the left usually
represents a country or region. The following is a list of
those regions.
IPADDR REGION(s)
-----------------------------------------------
44.002 USA: California: Sacramento
44.004 USA: California: Si Valley - SFO
44.006 USA: California: Sta Barb/Ventura
44.008 USA: California: San Diego
44.010 USA: California: Orange Countyl
44.012 USA: Eastern Washington,Idaho
44.014 USA: Hawaii & Pacific Islands
44.016 USA: California: Los Angeles/Valley
44.017 USA: California: Antelope/Kern County
44.018 USA: California: San Brdo & Riverside
44.020 USA: Colorado: Northeast
44.022 USA: Alaska
44.024 USA: Washington:Western/Puget
44.026 USA: Oregon
44.028 USA: Texas: North
44.030 USA: New Mexico
44.032 USA: Colorado: Southeast
44.034 USA: Tennesee
44.036 USA: Georgia
44.038 USA: South Carolina
44.040 USA: Utah
44.042 USA: Mississippi
44.044 USA: Massachusetts:western
44.046 USA: Missouri
44.048 USA: Indiana
44.050 USA: Iowa
44.052 USA: New Hampshire
44.054 USA: Vermont
44.056 USA: Eastern&Central Mass
44.058 USA: West Virginia
44.060 USA: Maryland
44.062 USA: Virginia
44.064 USA: New Jersey: northern
44.065 USA: New Jersey: southern
44.066 USA: Delaware
44.068 USA: New York:
44.069 USA: New York: WNY
44.070 USA: Ohio - old
44.071 USA: Ohio - new
44.072 USA: Illinois
44.073 USA: Illinois
44.074 USA: North Carolina (east)
44.075 USA: North Carolina (west)
44.076 USA: Texas: south
44.077 USA: Texas: west
44.078 USA: Oklahoma
44.080 USA: Pennsylvania: eastern
44.082 USA: Montana
44.084 USA: Colorado: Western
44.086 USA: Wyoming
44.088 USA: Connecticut
44.090 USA: Nebraska
44.092 USA: Wisconsin
44.094 USA: Minnesota
44.096 USA: District of Columbia
44.098 USA: Florida
44.100 USA: Alabama
44.102 USA: Michigan
44.104 USA: Rhode Island
44.106 USA: Kentucky
44.108 USA: Louisiana
44.110 USA: Arkansas
44.112 USA: Pennsylvania: western
44.114 USA: N&S Dakota
44.116 USA: Oregon:NW&PDX,Vancouver
44.118 USA: Maine
44.120 USA: special use in Nevada
44.122 USA: Kansas Puckett
44.123 USA: Virgin Islands
44.124 USA: Arizona
44.125 USA: Southern Nevada, Northern Nevada
44.126 Puerto Rico
44.128 Reserved for testing
44.129 Japan
44.130 Germany
44.131 United Kingdom
44.132 Indonesia
44.133 Spain
44.134 Italy
44.135 Canada
44.136 Australia
44.137 Netherlands
44.138 Israel
44.139 Finland
44.140 Sweden
44.141 Norway
44.142 Switzerland
44.143 Austria
44.144 Belgium
44.145 Denmark
44.146 Philippines
44.147 New Zealand
44.148 Ecuador
44.149 Hong Kong
44.150 Slovenija
44.151 France
44.152 Venezuela
44.153 Argentina
44.154 Greece
44.155 Ireland
44.156 Hungary
44.157 Chile
44.158 Portugal
44.159 Thailand, Laos, Vietnam, Kampuchea
44.160 South Africa
44.161 Luxembourg
44.162 Cyprus
44.163 Central America: Panama, Costa Rica, Nicaragua,
44.163 Central America: Honduras, El Salvador
44.163 Central America: Guatamala, Belize, Netherland Antilles
44.164 Surinam, French Guiana, Guyana, Mozambique
44.164 Atlantic Equitorial Islands, Martinique
44.164 Trinidad&Tobago, Falkland Islands, Aruba
44.165 Poland
44.166 Korea
44.167 India, Bangladesh, Nepal, Burma
44.168 China, Taiwan
44.169 African Continent
44.170 Croatia
44.171 Colombia, Peru, Uruguay
44.172 Sri Lanka, Malaysia
44.173 Mexico
44.174 Brazil
44.175 Cuba, Dominican Republic, Haiti
44.176 Turkey
44.177 Czech Republic
44.178 Russia
44.179 Gibraltar, Malta/Gozo
44.180 Yugoslavia(Serbia&Montenegro)
44.181 Slowak Republic
44.182 Romania
44.183 Iceland
44.184 Lebanon
44.185 Bulgaria
44.186 Singapore
44.187 Lithuania, San Marino
44.188 Armenia, Azerbaijan, Belarus, Estonia, Georgia,
44.188 Kazakhstan, Kyrgyzstan, Latvia, Moldova,
44.188 Tajikstan, Turkmenistan, Ukraine, Uzbekistan
44.189 Bosnia & Herzegovinia
44.190 Pacific Islands, Guam
44.193 Outer Space
44.194 Oceana
44.195 Antarctica
44.196 Arctic
IPENCAP
IPENCAP(9) XROUTER REFERENCE MANUAL 17/10/2023
NAME
IPENCAP -- IP-in-IP Encapsulation.
DESCRIPTION
The orginal form of IP-within-IP encapsulation, used by
KA9Q NOS to tunnel amateur IP (amprnet or 44-net) datagrams
via the public Internet, was IPIP, which used protocol number
94. Somewhere in the mists of time, the protocol number was
changed to 4 and the protocol was renamed IPENCAP (usally
referred to as ENCAP, but sometimes still called IPIP).
The structure of both types is the same, and is shown below.
Only the IP "protocol" number is different. It can be seen
that the amprnet (inner) datagram is carried within the
"payload" section of a public (outer) IP datagram:
.------------------.--------------------------.
| Public IP header | Amprnet IP datagram |
'------------------'--------------------------'
<-------------- Public IP datagram ----------->
Unfortunately IPENCAP is deliberately blocked by Windows,
starting with XP Service Pack 2, as a "security measure".
Therefore, **unless you use the NdisXpkt driver**, it is not
possible to use IPENCAP via an **Ethernet adaptor** with XR32.
This is a Windows problem, not an XR32 problem!! However, it
is still possible to use IPEncap via SLIP and PPP links.
(Note that the older form of the protocol, IPIP (protocol 94)
*isn't* blocked by Windows, and may be therefore be used
without NdisXpkt.)
There are no sush restrictions on the DOS and Linux versions
of XRouter.
IPENCAP can be used to route amprnet datagrams across *any*
TCP/IP network, not just the Internet. For example it can be
used to tunnel datagrams between nodes on a LAN. In this case
the "outer" IP header would contain LAN IP addresses, and the
"inner" header might contain amprnet IP addresses.
The IPENCAP protocol is used extensively between amprnet
gateways. The routing entries to achieve this are found in
file ENCAP.TXT (usually only available by secure FTP). See
the MAN page for ENCAP.TXT for more info.
Configuring IPENCAP
~~~~~~~~~~~~~~~~~~~
Note: For the purposes of this guide it is assumed that your
connection to the Internet is via a domestic NAT/PAT router
with firewall.
This may sound obvious, but in order to create any form of
tunnel between amprnet hosts, each host needs both an amprnet
(44.x.x.x.) and a public (e.g. 62.x.x.x) address. You MUST
ensure that your amprnet IP address is specified as XRouter's
"main" address, by including the line IPADDRESS=44.x.x.x near
the top of the XROUTER.CFG file (replacing x.x.x with your IP
address).
If you are using the EXTERNAL interface (which allows XRouter
to use its own IP stack), you then "override" the main address
on the port which connects to the LAN or Internet, by
including a different IPADDRESS= statement in the PORT block.
If you are not using the EXTERNAL interface, Windows or Linux
provides the LAN/Internet IP address for you.
Secondly, you and your link partner(s) must set up and test
IP routing between your public (i.e. non-44.x.x.x) IP
addresses. You cannot proceed until this step is complete!
IPENCAP encapsulation is specified by IP ROUTE entries with
mode "e" (encap). For example, the format to use in
IPROUTE.SYS is as follows:
IP ROUTE ADD 44.131.91.0/24 66.23.18.2 0 encap
The first IP address is the amateur IP address, or range
thereof, to be routed via this IPENCAP tunnel. If you don't
fully understand this format, see the MAN page for the IP
command.
The second address is the public IP address or hostname of the
link partner to whom the first address(es) will be routed. It
is more efficient to use an IP address if possible, rather
than a hostname, but the hostname may be required if the
partner's public IP address changes frequently. (DO NOT put
the partner's 44-net address in here!)
The last but one field (which is normally an XRouter PORT
number in normal route entries) is ignored and you set it to
zero.
Mode "encap" signifies IPENCAP encapsulation.
In ENCAP.TXT and XENCAP.TXT the format is as follows:
route addprivate 44.0.0.0/8 encap 66.23.18.2
In either case the mode "encap" can be abbreviated to "e"
alone.
Be aware that IPENCAP is subject to your access control rules,
and depending on your existing rules you may need to add the
following line to your rules in IPROUTE.SYS...
ACL PERMIT 0.0.0.0/32 0.0.0.0/0
Internet Routers
~~~~~~~~~~~~~~~~
If you wish to route IPENCAP across the Internet, don't forget
to specify a routing for IP *protocol* 4 (note *protocol* not
TCP/UDP port) in any "front-end" routers:
If XRouter is indirectly connected to the Internet via an
intermediate router, that router will probably be using some
form of NAT (Network Address Translation) to share one
"public" IP address between several systems on your LAN. The
"front end" router will probably route outgoing IPENCAP
without problem, but it will not know where to send incoming
IPENCAP unless explicitly configured.
Configuring such a router for IPENCAP usually involves
specifying a protocol number (4 for IPENCAP), and the LAN IP
address of a machine to which it should be routed, i.e.
XRouter's LAN IP address.
You are advised that not all domestic routers can be
configured to route *incoming* IPENCAP as it is not a
commercially recognised protocol. Some routers only allow
TCP and UDP port forwarding, with no provision for any other
protocol. If you or your link partner have such a router,
you may need to consider IPUDP instead.
SEE ALSO
ENCAP.TXT(8) -- Amprnet Encapsulated Routing File.
IP(1) -- IP Routing / Configuration Commands.
IPIP(9) -- IPIP Protocol.
IPROUTE.SYS(8) -- IP Routing / Configuration File.
IPUDP(9) -- IP-within-UDP Encapsulation.
XROUTER.CFG(8) -- Main Configuration File.
IPIP
IPIP(9) XROUTER REFERENCE MANUAL 17/10/2023
NAME
IPIP -- IPIP Encapsulation.
DESCRIPTION
IPIP is the "old" form of IP-within-IP encapsulation, used by
KA9Q NOS to tunnel amateur IP (amprnet or 44-net) datagrams
via the public Internet. Somewhere in the mists of time, the
protocol number was changed to 4 and the protocol was renamed
IPEncap (usally referred to as ENCAP).
The structure of both types is the same, and is shown below.
Only the IP "protocol" number is different. It can be seen
that the amprnet (inner) datagram is carried within the
"payload" section of a public (outer) IP datagram:
.------------------.--------------------------.
| Public IP header | Amprnet IP datagram |
'------------------'--------------------------'
<-------------- Public IP datagram ----------->
Unfortunately IPEncap is deliberately blocked by Windows,
starting with XP Service Pack 2, as a "security measure".
Therefore, **unless you use the NdisXpkt driver**, it is not
possible to use IPEncap with XR32. This is a Windows
problem, not an XR32 problem!! There are no such restrictions
on the DOS and Linux versions of XRouter.
IPIP provides an alternative to IPEncap that ISN'T blocked by
Windows. If you are using the NDIS driver, IPIP is provided
automatically. If you are not using NDIS, you need to put
IPIP=1 in XROUTER.CFG in order to activate IPIP.
IPIP can be used to route amprnet datagrams across *any*
TCP/IP network, not just the Internet. For example it can be
used to tunnel datagrams between nodes on a LAN. In this case
the "outer" IP header would contain LAN IP addresses, and the
inner IP header might contain amprnet addresses.
Configuring IPIP
~~~~~~~~~~~~~~~~
Note: For the purposes of this guide it is assumed that your
connection to the Internet is via a domestic NAT/PAT router
with firewall.
This may sound obvious, but in order to create any form of
tunnel between amprnet hosts, each host needs both an amprnet
(44.x.x.x.) and a public (e.g. 62.x.x.x) address. You MUST
ensure that your amprnet IP address is specified as XRouter's
"main" address, by including the line IPADDRESS=44.x.x.x near
the top of the XROUTER.CFG file (replacing x.x.x with your IP
address).
If you are using the EXTERNAL interface (which allows XRouter
to use its own IP stack), you then "override" the main IP
address on the port which connects to the LAN or Internet, by
including a different IPADDRESS= statement in the PORT block.
If you are not using the EXTERNAL interface, Windows or Linux
provides the LAN/Internet IP address for you.
Secondly, you and your link partner(s) must set up and test
IP routing between your public (i.e. non-44.x.x.x) IP
addresses. You cannot proceed until this step is complete!
IPIP encapsulation is specified by IP ROUTE entries with mode
"i". For example, the format to use in IPROUTE.SYS is as
follows:
IP ROUTE ADD 44.131.91.0/24 66.23.18.2 0 ipip
The first IP address is the amateur IP address, or range
thereof, to be routed via this IPIP tunnel. If you don't
fully understand this format, see the MAN page for the IP
command.
The second address is the public IP address or hostname of the
link partner to whom the first address(es) will be routed. It
is more efficient to use an IP address if possible, rather
than a hostname, but the hostname may be required if the
partner's public IP address changes frequently. (DO NOT put
the partner's 44-net address in here!)
The last but one field (which is normally an XRouter PORT
number in normal route entries) is ignored and you set it to
zero.
Mode "ipip" signifies IPIP encapsulation.
In XENCAP.TXT the format is as follows:
route addprivate 44.0.0.0/8 ipip 66.23.18.2
In either case the mode "ipip" can be abbreviated to "i"
alone. Mode "ipip" is allowed in XENCAP.TXT but not in
ENCAP.TXT.
Be aware that IPIP is subject to your access control rules,
and depending on your existing rules you may need to add the
following line to your rules in IPROUTE.SYS...
ACL PERMIT 0.0.0.0/32 0.0.0.0/0
Internet Routers
~~~~~~~~~~~~~~~~
If you wish to route IPIP across the Internet, don't forget to
specify a routing for IP *protocol* 94 (note *protocol* not
TCP/UDP port) in any "front-end" routers:
If XRouter is indirectly connected to the Internet via an
intermediate router, that router will probably be using some
form of NAT (Network Address Translation) to share one
"public" IP address between several systems on your LAN. The
"front end" router will probably route outgoing IPIP without
problem, but it will not know where to send incoming IPIP
unless explicitly configured.
Configuring such a router for IPIP usually involves specifying
a protocol number (94 for IPIP), and the LAN IP address of a
machine to which it should be routed, i.e. XRouter's LAN IP
address.
You are advised that not all domestic routers can be
configured to route *incoming* IPIP as it is not a
commercially recognised protocol. Some routers only allow
TCP and UDP port forwarding, with no provision for any other
protocol. If you or your link partner have such a router,
you may need to consider IPUDP instead.
SEE ALSO
IP(1) -- IP Routing / Configuration Commands.
IPENCAP(9) -- IPENCAP Protocol.
IPROUTE.SYS(8) -- IP Routing / Configuration File.
IPUDP(9) -- IP-within-UDP Encapsulation.
XROUTER.CFG(8) -- Main Configuration File.
IP-PRIMER
IP-PRIMER(9) XROUTER REFERENCE MANUAL 17/10/2023
NAME
IP-PRIMER -- IP Addressing / Routing Primer.
IP ADDRESSES
All IP addresses consist of a 32 bit binary number, which
is composed of four 8-bit binary numbers. For clarity they
are usually expressed as four decimal numbers separated by
dots, the so called "dotted quad" form, for example
44.131.91.2.
Each of the numbers which make up the quad can range from
0 to 255, i.e. 256 numbers in total. The numbers 0, 128
and 255 are usually reserved for special purposes.
The most significant (leftmost) number identifies the
"network" within the whole Internet. 44 was originally
allocated to Amateur Packet Radio, or "ampr.org". However,
the upper quarter of this range has now been sold off, so
44 is no longer exclusively amprnet.
Within the so-called "amprnet", the second number from the
left usually identifies the country, although in the USA it
generally identifies a state. In some parts of the world it
identifies a group of countries. In our example 131 is the
code for the whole UK. Numbers 192 and above no longer
belong to amprnet.
The third number from the left identifies the "region"
within the country or state, and in our example region 91
is North Worcestershire.
The rightmost number identifies up to 256 separate users
within the region. The addresses within a region are
sometimes allocated on a first come first served" basis,
or sometimes in groups to allow further subdivision of a
region.
IP ROUTING
Unlike NetRom routing, IP routing is often explicitly defined
by the sysop, although just like NetRom it can be automated
using RIP (Routing Information Protocol). The IP equivalent
of a NetRom "nodes table" is the "IP routes table". This can
be initialised using entries in IPROUTE.SYS.
The basic idea is that, for any destination IP address,
XRouter must send the IP packet (usually called a
"datagram") either directly to the destination (if it's on
the LAN or within radio range), or to a "gateway" which
knows how to reach the destination. In the most extreme
case, you can simply send all non-local IP traffic to a
gateway, who will handle it for you.
Since there are billions of IP addresses, it would be
impractical to define a route for every possible
destination. This is where the hierarchical structure
of IP addresses come to your aid.
If you are in the USA, you don't need to know explicitly
how to route to everyone in the UK. All you need to know
is how to route to the UK, then the routers within the UK
will do the work for you. If you don't know a route to
the UK, simply route the traffic to a gateway who does.
There is always someone willing to act a a gateway on your
behalf.
Routing decisions are made using a special combination of
IP addresses and "bits", for example 44.0.0.0/8. This tells
XRouter to compare the destination IP address of datagrams
with the leftmost 8 bits of 44.0.0.0, ignoring the
rightmost 24 bits. This will match any address beginning
with 44, i.e. the whole of amprnet (as was). Since the
rightmost 24 bits are ignored, 44.131.91.2/8 would have
*exactly* the same effect.
The higher the number of bits, the more precise the match,
for example 44.131.0.0/16 would "catch" all datagrams
addressed to the UK, 44.131.91.0/24 would catch all
datagrams addressed to North Worcestershire, UK, and
44.131.91.2/32 would match only one destination, namely
44.131.91.2. The "/32" is always the default if the
number of bits is not specified.
Having "caught" a destination, the remainder of a routing
entry tells XRouter which gateway (if any) to send it to,
which port to send it on, and what mode to use.
IP routing is usually specified in IPROUTE.SYS using
commands like this:
IP ROUTE ADD <host>[/len] <gateway> <port> [mode [metric]]
Example: IP ROUTE ADD 44.131.93.0/24 44.131.93.240 5 d
This would route all region 93 traffic (44.131.93.0 -
44.131.93.255) to the gateway 44.131.93.240 on port 5
using datagram mode.
ROUTING MODES
The routing [mode] indicates how the traffic is to to be
handled, and is specified using a single letter as
follows:
d = Datagram (direct)
e = Encap (ip-over-ip protocol 4)
i = IPIP (ip-over-ip protocol 94)
n = Netrom (ip-over-netrom)
r = Reject
s = Silent discard
u = IPUDP (ip-over-UDP)
v = Virtual circuit (ip-over-ax25)
k = Kernel
"Datagram" is the usual mode, and is the default if "mode"
is omitted. It transmits datagrams "raw" inside
SLIP, PPP, Ethernet or AX25 UI frames, according
to the protocol used on the the destination port.
There is no error correction at the link layer,
so datagram mode should only be used on wire
links, or RF links with low loss rates.
"Virtual Circuit" mode gives better performance on less
than perfect RF links. It transports the
IP datagrams inside AX25 <I> frames,
detecting and correcting errors at the
link layer.
"Netrom" mode is less efficient, but can "tunnel" datagrams
across non-ip sections of the network by wrapping
them in Netrom layer 3 frames.
"Encap" mode is used for IP/IP encapsulation, i.e. sending
44-net datagrams across the Internet by "wrapping"
them in datagrams with public Internet addresses.
This uses IP protocol number 4. Unfortunately, in
some cases Windows blocks this protocol (see below).
"IPIP" is the original IP-within-IP encapsulation mode,
using IP protocol number 94, and has the advantage
that it is not blocked by Windows.
"IPUDP" mode is similar to Encap and IPIP, except that the
datagrams are first wrapped in UDP before being
transported in IP. The advantage is that UDP is
usually able to pass through routers which don't
support IPIP or IPEncap, and can be selectively
routed to different machines according to the UDP
service port numbers.
"Reject" entries are used to reject traffic destined for
systems which don't exist, or are which not
reachable via any port. If simply routed on the
default port, such datagrams would waste resources
and would probably end up looping back to us.
Datagrams matching a "reject" entry are rejected
by returning an ICMP "destination unreachable"
report to the sender. The "gateway" ip address
should be 0.0.0.0 and the port number is ignored.
"Silent Discard" entries are similar to "Reject", except
that they simply dump the unwanted
datagrams without sending an ICMP error
report. This saves bandwidth when the
problem is persistent, and is more
suitable than "Reject" for suppressing
malicious network probes.
"Kernel" mode is a dummy mode. It tells XRouter to use the
host operating system's TCP/IP services to handle
this traffic. It is intended only as a last resort,
e.g. when operating without the EXTERNAL intarface.
The host O/S allows XRouter to originate and
terminate TCP, UDP, IPIP, ICMP and AXIP, but not to
*route* those protocols. Therefore, using a mode
"k" entry you may Telnet and Ping from XRouter, but
you are not allowed to route 3rd party traffic, e.g.
from RF to Internet.
ENCAP BLOCKING
Starting with Windows XP Service Pack 2, the IPEncap (encap)
protocol 4 was blocked by Windows for so-called "security
reasons".
Therefore if you are using WinXPSP2 or a later O/S, encap
mode can only be used via Ethernet if XR32 is able to
bypass Windows and talk directly to the Ethernet card using
the NDISXPKT driver. But this driver is currently only
available for Windows 2000 and XP.
This means that, until an NDIS driver is written for later
versions of Windows, you are not able to use encap mode on
those platforms.
However this only applies to Ethernet. If you have a SLIP
or PPP (i.e. serial cable) link with another system, you
may use encap mode whatever operating system is in use.
Linux does not block IPEncap, but you may need to give
XRouter the required privileges to use it.
ADDRESS RESOLUTION PROTOCOL (ARP)
ARP is responsible for mapping gateway IP addresses to
"hardware" (i.e. AX25 or Ethernet) addresses.
In order to send an IP datagram over an AX25 or Ethernet
network, it must be "wrapped" in an AX25, Ethernet, or
Netrom packet, and that packet will need a destination
address appropriate to that network. For example, to route
a datagram to 44.131.91.2 it must be wrapped in an AX25
packet addressed to GB7PZT-5.
The system *will* sometimes work without any ARP entries,
due to the process of "ARP resolution", whereby a router
can make a broadcast asking adjacent systems if they know
the hardware address for a given IP address, but this
process takes time and the adjacent routers may not know
the answer. Thus, for RF links at least, it is advisable
to put ARP entries for each of your direct RF neighbours
int IPROUTE.SYS. The general form of an ARP entry is:
ARP <ADD | PUBLISH> <host> <hwtype> <hwaddr>
<host> is the neighbour's IP address in dotted quad form.
<hwtype> is the hardware address type, i.e. "ax25"
"netrom" or "ether".
<hwaddr> is the hardware address, i.e. AX25 callsign or
Ethernet address.
Example ARP entries:
This one causes datagrams bound for 44.131.90.6 to be
wrapped in AX25 packets addressed to GB7IPT-9:
arp add 44.131.90.6 ax25 GB7IPT-9
Whereas the following will send datagrams bound for
44.131.95.7 to the G7GHP-5 system via the GB7DIG digipeater.
Up to 8 digipeaters may be used in a single comma-delimited
string:
arp add 44.131.95.7 ax25 G7GHP-5,GB7DIG
This one will wrap datagrams destined for 44.131.24.1 in
Netrom packets addressed to node GB7CX:
arp add 44.131.24.1 netrom GB7CX
The following will wrap the datagrams in ethernet packets.
arp add 44.131.91.9 ether 00:00:1B:2C:04:81
ARP PUBLISH is used in cases where one system is "hidden"
behind another, and allows other systems to discover the
correct hardware address to use.
For example, say 44.131.91.127 is only reachable via
44.131.91.245. Unless all the local systems were
specifically configured to route to 91.127 via 91.245,
they wouldn't know how to do it. Including the entry:
"arp publish 44.131.91.127 ax25 g8pzt" on the 91.245
(g8pzt) router causes it to respond to anyone who asks
for the hardware address for 91.127, giving its own ax25
address.
SEE ALSO
ARP(1) -- Address Resolution Protocol Commands.
IP(1) -- IP Routing / Configuration Commands
IPROUTE.SYS(8) -- IP Router Control File.
IPUDP
IPUDP(9) XROUTER REFERENCE MANUAL 17/10/2023
NAME
IPUDP -- IP-over-UDP Tunnelling.
DESCRIPTION
The "Amateur Packet Radio IP Network" (amprnet) is a private
network for transferring TCP/IP between amateur radio
stations. It was originally assigned the class A IP address
block 44.x.x.x, but although it is notionally part of the
wider Internet, the public Internet has limited knowledge of
how to route it.
To solve this problem, amprnet traffic is usually wrapped or
"encapsulated" within publicly-routable IP datagrams. At the
destination gateway the frame is "unwrapped" to reveal the
original amprnet datagram.
IPUDP is IP encapsulated in UDP/IP. It allows amateur IP to
be transported across other IP networks such as the Internet,
to form "Virtual Private Networks" (VPN's).
In contrast to IPIP and IPEncap, which transport the private
(e.g. amateur) IP directly inside the payload portion of a
public (e.g. Internet) IP datagram, IPUDP transports the
private datagram in the payload portion of a UDP frame, which
is itself transported as payload in a public IP datagram.
This requires 8 bytes more overhead than IPIP, but it is far
more flexible.
.------------------.----------------------------------.
| Public IP header | UDP Header | Amprnet IP datagram |
| 62.31.20.2 | 94->94 | 44.131.91.2 |
| -> 82.31.65.8 | | ->44.68.1.5 |
'------------------'------------'---------------------'
<---------------- Public IP datagram --------------->
IPUDP Packet Structure
(In the above diagram, the amprnet (44-net) datagram
forms the payload of a publicly-routable UDP/IP
datagram. The IP addresses are for illustrative
purposes only.)
IPIP and IPENCAP, hereafter collectively referred to as
IP-in-IP, are "portless" protocols, and it is therefore
difficult (in come cases impossible) to make them pass
through some types of domestic NAT / PAT router which rely on
translating TCP and UDP service port numbers in order to
share a public IP address among several LAN hosts.
IPUDP overcomes this limitation because it transports the data
using a well known protocol (UDP) which NAT / PAT routers can
understand, thus it can get through where IP-in-IP cannot.
For example, it is easy to configure even the most basic
domestic router to route incoming UDP port 94 to a specific
machine on the LAN, but it is not often possible to do the
same with IP *protocol* 4.
The IPUDP protocol currently defaults to UDP port 94 for no
better reason than because the number was easy to remember,
being the same as the original protocol number for IPIP. In
addition, there were no other well-known protocols using this
port number. If difficulties are encountered with port 94,
please inform the protocol originator (G8PZT). There's nothing
to stop you using any other UDP port number.
IPUDP is only used for tunnelling amateur IP through the
public Internet, or for situations where conventional routing
isn't possible (e.g. XR32 without NdisXpkt). It would be
pointless when routing via a radio link.
IPUDP tunnels are one-way. To create two-way IPUDP routing,
the other end of a link needs to set up a reverse tunnel.
However, the reverse route needn't necessarily use a tunnel.
When To Use IPUDP
~~~~~~~~~~~~~~~~~
If you are running a Linux version of XRouter, most of this
following section may be ignored, and you can jump to the
final two paragraphs...
The Windows version of XRouter (XR32) was originally designed
to be used with the NdisXpkt driver, which allowed it to have
its own LAN IP address and IP stack. In this mode it could
route anything, just like its DOS predecessor (XR16).
However, there is no 64-bit version of the NdisXpkt driver,
so XR32 was subsequently made "dual-mode", such that it could
be made to run with or without the driver.
Without the NdisXpkt driver, XR32 was forced to use facilities
provided by the Windows TCP/IP stack. Those facilities were
limited, and in some cases were deliberately crippled by
Microsoft. For example, later versions of Windows XP prevent
the use of IPENCAP (protocol number 4).
Since no-one likes having to install and load drivers, the
majority of sysops now tend to use XR32 without NdisXpkt.
However this is a "basic" mode, with limited facilities,
compared to the "full" (NdisXpkt) mode. It was only intended
as a stop-gap measure, until a 64-bit driver could be written.
In basic mode, XR32 can originate and terminate all the common
protocols (TCP, UDP, ICMP etc.), but cannot actually route raw
IP via the *Ethernet* NIC without some form of encapsulation.
(SLIP / PPP connections are not restricted in this way)
As mentioned above, XR32 in "basic" mode cannot currently use
the IPENCAP protocol, so your options for routing IP via an
Ethernet NIC are limited to the following:
a) Route IP across existing AXUDP/AXIP links.
This is the least efficient in terms of packet overhead,
although that is of litle concern on a broadband
connection! It is easy to set up, but the downside is that
you can only route traffic to your immediate AXUDP or AXIP
neighbours, not the wider world. However, if everyone sets
up their default routes to direct the traffic to and from
an IPENCAP-capable gateway, this should be no barrier.
b) Use original IPIP protocol (protocol number 94).
This is the most efficient, and allows you to make a single
hop (as far as 44-net is concerned) tunnel to *any*
gateway that can accept IPIP protocol 94. In order to
receive this protocol however, your Internet router must be
capable of routing by PROTOCOL, which many routers aren't.
This protocol doesn't involve AX25 at all.
c) Use IPUDP protocol.
This option also allows you to hop directly to any other
gateway, providing they can handle IPUDP, and it doesn't
use AX25. It is only marginally less efficient than IPIP,
and as mentioned previously, it has the advantage that it
is easy to route through NAT/PAT routers.
Although DOS and Linux versions of XRouter (and XR32 in
"full" mode) allow IPEncap, you cannot use IPEncap if your
Internet router can't handle it. In this case, IPUDP may be
the preferable option.
Even if your domestic Internet router can handle the IP-in-IP
protocols (4 and 94), it can only route such traffic to ONE
host on the LAN. But it can route IPUDP to multiple hosts, if
different UDP port numbers are used.
Creating An IPUDP Tunnel
~~~~~~~~~~~~~~~~~~~~~~~~
(Note: For the purposes of this guide it is assumed that your
connection to the Internet is via a domestic NAT/PAT router
with firewall.)
The following may sound obvious, but in order to create any
form of tunnel between amprnet hosts, each host needs both an
amprnet (44.x.x.x.) and a public (e.g. 62.x.x.x) address. You
MUST ensure that your amprnet IP address is specified as
XRouter's "main" address, by including the line
IPADDRESS=44.x.x.x near the top of the XROUTER.CFG file
(replacing x.x.x with your IP address).
If you are using the EXTERNAL interface (which allows XRouter
to use its own IP stack), you then "override" this IP address
on the Ethernet port, by including an IPADDRESS= statement in
the Ethernet PORT block. The IP adress should be approriate
for your LAN. If you are not using the EXTERNAL interface,
Windows or Linux provides the LAN IP address instead.
Secondly, you and your link partner(s) must set up and test IP
routing between your public (i.e. non-44.x.x.x) IP addresses.
You cannot proceed until this step is complete!
If you are using a domestic router between XRouter and the
Internet, you must "open" UDP port 94 to direct incoming IPUDP
traffic to XRouter's LAN address. This must be a "static"
(permanent and unchanging) translation, not a transient or
"port triggered" one.
Finally, for each tunnel destination you must add an IP route
entry into IPROUTE.SYS, similar to the following:
IP ROUTE ADD 44.131.91.0/24 62.31.206.176 0 u
The first IP address is the amateur IP address, or range
thereof, to be routed via this IPUDP tunnel. If you don't
fully understand this format, see the manual sections
detailing IPROUTE.SYS and the IP ROUTE ADD command.
The second address is the public IP address or hostname of the
link partner to whom the first address(es) will be routed. It
is more efficient to use an IP address if possible, rather
than a hostname, but the hostname may be required if the
partner's public IP address changes frequently. (DO NOT put
the partner's 44-net address in here!)
The last but one field (which is normally an XRouter PORT
number in normal route entries) is used in IPUDP entries to
modify the UDP service number. "0" is the recommended
setting, meaning "use default" (see below).
Mode "u" signifies IPUDP encapsulation.
Reassigning the IPUDP Port Number
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Since you can only have one application using a given UDP port
number per IP stack, you are not able to run more than one
copy of XRouter on the same machine unless you reassign or
disable the IPUDP ports to avoid contention. You may do this
using the IPUDPPORT=n keyword anywhere in XROUTER.CFG, where
n is a number between 0 and 65535.
It is recommended that you use port 94 (the default) as the
primary port, 95 as the first alternative, 96 for the second,
97 for the third, and so on, as these numbers are not assigned
to any particular service. You should avoid using the numbers
associated with standard services such as DNS (53), DHCP (67
and 68), AXUDP (93), WINS (135) and so on. For a
comprehensive list search for "assigned numbers" on the web.
Please bear in mind that if you reassign your IPUDP port,
others will not be able to route IPUDP to you unless you
inform them of the new number.
Routing to Alternative UDP port
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Creating an IPUDP tunnel to a peer who has reassigned his
IPUDP port is relatively simple, as the following example
shows:
IP ROUTE ADD 44.131.91.0/24 62.31.206.176 95 u
Note the "95" in the last but one field, which tells XRouter
to address the packets to UDP port 95 instead of the default
port 94. That's all there is to it!
Disabling IPUDP
~~~~~~~~~~~~~~~
If you are using XRouter for AX25/Netrom only, and don't wish
to take part in the amprnet, then you probably won't have
included an IPADDRESS= line in XROUTER.CFG. In this case all
IP facilities, including IPUDP, are disabled automatically.
However, you may have an IP address but wish to disable IPUDP
for other reasons. You can do this easily by including the
directive "IPUDPPORT=0", anywhere in XROUTER.CFG.
More Info
~~~~~~~~~
This file is too big already. For FAQ and troubleshooting
info, please see the MAN page entitled IPUDP-FAQ.
SEE ALSO
IP(1) -- IP Routing / Configuration Commands.
IPENCAP(9) -- IPENCAP Protocol.
IPIP(9) -- IPIP Protocol.
IPROUTE.SYS(8) -- IP Routing / Configuration File.
IPUDP(9) -- IP-within-UDP Encapsulation.
IPUDP-FAQ(9) -- IPUDP Frequently Asked Questions.
NDISXPKT(9) -- NDISXPKT Driver.
XROUTER.CFG(8) -- Main Configuration File.
IPUDP-FAQ
IPUDP-FAQ(9) XROUTER REFERENCE MANUAL 21/10/2023
NAME
IPUDP-FAQ -- IPUDP FAQ / Troubleshooting.
DESCRIPTION
This document contains Frequently Asked Questions and
troubleshooting information related to the IPUDP protocol.
It is a work in progress...
IPUDP Frequently Asked Questions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Q) Under what circumstances should I use IPUDP?
A) You might consider using IPUDP in the following
situations:
- When you cannot use IPEncap because are running XRouter
on Windows without the NdisXpkt driver.
- When your Internet router cannot handle "portless"
protocols such as IPIP, IPEncap, AXIP etc.
- When you have an existing system that requires your
Internet router to route IPENCAP to it (you can only
have one IPENCAP host per public IP address).
- When you have more than one system on the same public
IP address and require independent routing to each.
- When you have more than one XRouter on the same machine,
with different 44-net addresses.
- When you wish to route between 44-net systems on your
LAN that can't use IPEncap.
- Just for the fun of it! :-)
Q) Can I Send IPUDP To Anyone?
A) No. It is believed that IPUDP is only implemented by
XRouter at the time of writing.
Q) If I use IPUDP, can I still use other forms of IP routing?
A) Yes. You can safely "mix and match" your IP routing
modes to suit your own requirements. What you mustn't
do is have identical route table entries with different
modes. Nothing dangerous will happen, but XRouter will
ignore the duplicates.
Q) Do I need an AXIP interface to use IPUDP?
A) No. IPDUP is completely unrelated to AX25, AXIP, AXUDP
etc. and does not need a special INTERFACE or PORT.
Q) Do I need ENCAP.TXT?
A) No, not for IPUDP itself, but you may need it if you
intend to use IPEncap alongside IPUDP.
There is an XRouter-only version of ENCAP.TXT called
XENCAP.TXT, which can accept routing modes other than
"encap". Place it into your XRouter working directory
and type IP ROUTE LOAD to read it into your routing
table.
If you wish to add your system(s) to the list so that
they can receive IPUDP traffic, please email
g8pzt[at]blueyonder.co.uk, stating your callsign, the
subnet address(s) that you handle, your public IP
address, and your IPUDP port number if it isn't 94.
Troubleshooting
~~~~~~~~~~~~~~~
IPUDP is a well-proven technology. When things don't work,
it is always due to a configuration error, not a fault in
XRouter.
Try PINGing the destination host to see if XRouter generates
an error message. Some of the errors so far observed are
listed below:
o Boot up error: "IPUDP Initialisation error 20048"
The IPUDP port is already in use by another process on the
PC. This error is usually caused by trying to run more
than one XRouter on the same machine. You must use the
IPUDPPORT keyword in XROUTER.CFG to disable IPUDP on all
but one XRouter, or to assign a different port number to
each one.
o Error 9x02 (No memory)
This should never happen, but if it does, Windows must be
seriously overloaded! This is a transient error, and
should clear itself. If not, close some apps.
o Error 9206 (Permission denied)
The IP Access Control List is preventing the packet from
being sent because the combination of source and
destination IP addresses is not within one of the ranges
you have defined to be "legal". Possible causes are:
- XRouter's "main" IP address not defined, or is not a
44-net address.
- Incorrect configuration of IP Access Control List.
Try commenting out all the ACL entries in IPROUTE.SYS and
reloading the file. If this fixes the problem, there is
a faulty of missing entry. You may need to add the
following entry: ACL PERMIT 0.0.0.0/32 0.0.0.0/0
o Error 9411
The IPUDP subsystem was not initialised because the main IP
address was not defined, or because IPUDPORT is set to 0 in
XROUTER.CFG.
o No Response From Target
Assuming you have set up the route entry correctly, there
are many possible reasons for failure. The following list
is by no means exhaustive:
- Your system has no viable route to the target's public
IP address. Try PINGing or Telnetting to that address.
Note that if IP QUIET or firewalling is active, you may
not get a reply to your PINGs.
- There is a higher priority but non-functional route in
the IP routing table, preventing the IPUDP route from
being used.
- There's a problem with your or your partner's Internet
connection.
- The target system is currently off-line for maintenance.
- The target's sysop has disabled IPUDP, or has reassigned
the IPUDPPORT.
- The target's Internet router is not set up to route IPUDP
to his XRouter, or the response is via IPUDP and your
Internet router is not set up to route it to your
XRouter.
- The target's IP addresses are set up incorrectly.
- The target hasn't configured a route that leads back to
you. Note that he doesn't need to configure a *direct*
route back to you, he may send it via other routers or
gateways.
- An intermediate router is dropping the return packets.
- The response is IPUDP and the target is replying to the
wrong UDP port number.
- The response is via IPEncap and your Internet router is
not set up to route it, or your system is not using
NdisXpkt (Windows only), and can therefore not accept
IPEncap.
SEE ALSO
IP(1) -- IP Routing / Configuration Commands.
IPENCAP(9) -- IPENCAP Protocol.
IPIP(9) -- IPIP Protocol.
IPROUTE.SYS(8) -- IP Routing / Configuration File.
IPUDP(9) -- IP-within-UDP Encapsulation.
NDISXPKT(9) -- NDISXPKT Driver (Windows Only).
XROUTER.CFG(8) -- Main Configuration File.
IPUDP-FAQ(9) END OF DOCUMENT
KISS
KISS(9) XROUTER REFERENCE MANUAL 17/10/2023
NAME
KISS -- KISS Protocol.
DESCRIPTION
KISS (Keep It Simple, Stupid) is a simple protocol which
encapsulates AX25 frames for transmission over serial (e.g.
RS232) lines. The framing method is identical to SLIP.
There is no flow control or error handling in the original
protocol.
The protocol specifies the following special characters:
Name Hex Dec Purpose
---------------------------
FEND 0xC0 192 Frame End
FESC 0xDB 219 Frame Escape
TFEND 0xDC 220 Transposed FEND
TFESC 0xDD 221 Transposed FESC
The FEND characters mark the start and end of the frame
containing the encapsulated datagram as follows:
.------.------.-------.------.
| FEND | Type | Data | FEND |
'------'------'-------'------'
In order to ensure that the FEND character only occurs at the
start and end of the frame, FENDs which occur within the
unencapsulated data are "escaped" to the two byte sequence
FESC TFEND. Likewise FESC is escaped to the sequence
FESC TFESC.
It is permissible (but not obligatorry) for two frames to
share a FEND:
.------.------.-------.------.------.-------.------.
| FEND | Type | Data | FEND | Type | Data | FEND |
'------'------'-------'------'------'-------'------'
The first byte of each frame, after the FEND, is a "type"
indicator. This byte is broken into two 4-bit nibbles such
that the low-order nibble indicates the command number (given
in the table below) and the high-order nibble indicates the
port number for that particular command. In systems with
only one HDLC port, it is by definition Port 0. In
multi-port TNCs, the upper 4 bits of the type indicator byte
can specify one of up to sixteen ports.
The following commands are defined:
Command Function Comments
--------------------------------------------------------------
0 Data frame The rest of the frame is data received
from / to be sent to the HDLC channel.
1 TXDELAY The next byte is the transmitter keyup
delay in 10 ms units. The default
start-up value is 50 (i.e. 500 ms).
2 PERSIST The next byte is the persistence
parameter, p, scaled to the range 0-255
with the following formula: P=p*256-1
The default value is P=63 (i.e. p=0.25).
3 SLOTTIME The next byte is the slot interval in 10
ms units. The default is 10 (i.e. 100ms).
4 TXTAIL The next byte is the time to hold up the
TX after the FCS has been sent, in 10 ms
units. This command is obsolete, and is
included here only for compatibility
with some existing implementations.
5 FULLDUP The next byte is 0 for half-duplex,
nonzero for full-duplex. The default is 0
(i.e. half-duplex).
6 SetH/w Specific for each TNC. In the TNC-1,
this command sets the modem speed. Other
implementations may use this function for
other hardware-specific functions.
255 Return Exit KISS and return control to a higher
level program. This is useful only when
KISS is incorporated into the TNC along
with other applications.
--------------------------------------------------------------
Only command 0 is allowed in frames from TNC to host.
Commands 1 to 6 are used to set TNC parameters, and are
usually sent at 5 minute intervals.
Limitations Of Plain KISS
~~~~~~~~~~~~~~~~~~~~~~~~~
In the original protocol, there is no error detection to
protect against noise and corruption on the RS232 lines.
More seriously, the host has no way of knowing how much data
is queued in the TNC awaiting transmission. A busy channel
could prevent the TNC from transmitting, causing the host's
FRACK timer to repeat frames, which simply add to the queue.
When the channel clears, the original frame and all the
repeats are spewed out in one huge transmission, causing the
other end of the link to respond with a load of acks. In bad
cases, the AX25 module retries out, so when the channel
clears, the original frame, plus repeats, plus a string of
<DISC> frames are sent!
KISS With Checksum
~~~~~~~~~~~~~~~~~~
Checksum-KISS appends a single byte checksum to the "data"
portion of the frame, to detect line errors. Frames that
fail the checksum test are silently discarded. The upper
layer eventually detects the loss and re-sends the frame.
KISS With Acknowledgement (ACKMODE)
~~~~~~~~~~~~~~~~~~~~~~~~~
When operating in this mode, the host attaches a 16-bit
"serial number" to each frame (between the "type" and "data"
fields), and the TNC sends an "acknowledgement" frame to the
host when it has transmitted that frame on-air. This enables
the host to know how much data is queued, and to start its
AX25 timers at the correct time. This mode uses the command
code of 12 for both data frames and the acknowledgements.
Polled KISS
~~~~~~~~~~~
In this mode, the TNC does not send any data to the host until
it is asked to do so by a POLL command (command number 14).
This allows several TNC's to be multiplexed together (usually
with a diode matrix) onto one COM port, which removes the need
for one COM port per TNC. Up to 16 TNC's can be multiplexed
onto one COM port. Each TNC must have a different "address",
i.e. in the upper nybble of the Type field.
Serial Line Parameters
~~~~~~~~~~~~~~~~~~~~~~
Serial lines used for KISS must run at 8 data bits. Flow
control must be hardware or none, as XON/XOFF flow control
would interfere with the protocol.
If flow control is used, the cable must contain at least 5
cores, namely TXD, RXD, RTS, CTS and GND. If flow control is
not used, only TXD, RXD and GND are required.
When KISS is used to connect a PC to a TNC, a "straight
through" cable is used, because a TNC is considered a DTE
(Data Terminal Equipment).
When KISS is used to interconnect two applications, some form
of NULL MODEM is required. In the case of "real"
RS232 this could be an actual null modem device, or a cable
that is wired such that the TXDs at each end go to the RXDs
at the other end, and the RTSs at each end go to the CTSs at
the other. "Virtual" COM port pairs such as Com0Com include
this functionality as standard.
Configuring a KISS Link
~~~~~~~~~~~~~~~~~~~~~~~
KISS can be used to link XRouter with KISS TNC's, or with
other KISS systems via real or "virtual" COM ports. A typical
configuration in XROUTER.CFG would be as follows:
INTERFACE=1
TYPE=ASYNC <-- Serial RS232
COM=1 <-- COM port number (*)
PROTOCOL=KISS <-- Use KISS
SPEED=38400 <-- Baud rate
FLOW=0 <-- No flow control
MTU=256 <-- See below
KISSOPTIONS=NONE <-- Plain KISS
ENDINTERFACE
(*) On Linux versions COM specifies a TTY device name.
MTU specifies the largest size for the data portion of an AX25
frame, and the largest IP datagram that can be handled. This
should be set to 256 for KISS TNC's because they usually have
small packet buffers. For KISS links not using TNC's, MTU may
be set larger, up to 1500.
KISSOPTIONS are as follows:
NONE - Plain KISS (most TNC's use this) (default)
POLLED - For TNCs which send only when polled.
CHECKSUM - Packets protected by checksum. You can
only use this option if your TNC supports it.
ACKMODE - For TNC's which inform XRouter when a frame has
been transmitted on air.
SLAVE - XRouter will act like a polled KISS TNC,
sending only when commanded to do so.
Polled and slave are mutually exclusive.
BPQKISS eproms require POLLED and CHECKSUM, and their use
of ackmode is optional.
The PORT is configured like this:
PORT=3
ID=144.675MHz User Port
INTERFACENUM=1
CHANNEL=B
ENDPORT
CHANNEL is only required if the TNC is not using its default
channel / port.
KISS TNC's
~~~~~~~~~~
Most TNC's can be switched into KISS mode using a command
such as "KISS ON", but they have a tendency to randomly drop
back to command mode. Therefore it is more usual to replace
the EPROM with a purpose made KISS EPROM. There are several
versions, such as BPQKISS, JKISS, KISS and 220KISS. These
usually default to channel A, but can be "patched" for other
channels.
For example the BPQKISS EPROM may be patched for different
KISS channels by changing the byte at address 20(hex) in the
PROM as follows:
Channel Byte-20h Channel Byte-20h
---------------- ----------------
A 00h I 80h
B 10h J 90h
C 20h K A0h
D 30h L B0h
E 40h M C0h
F 50h N D0h
G 60h O E0h
H 70h P F0h
Once in KISS mode, the only way to switch a conventional TNC
back to normal mode is to send the sequence 192, 255, 192 on
the serial line. This can be done using a terminal program
and the numeric keypad, or a simple program such as
KISSOFF.EXE.
Dial-Up KISS
~~~~~~~~~~~~
A temporary KISS connection may be established over an XRouter
dial-up link using the MODE command in the DUN script. This
is only likely to be of use where phone calls are free!
SEE ALSO
DUN(9) -- Dial-up Networking.
SLIP(9) -- Serial Line Internet Protocol.
XROUTER.CFG(8) -- Main Configuration File.
L2FRAG
L2FRAG(9) XROUTER REFERENCE MANUAL 17/10/2023
NAME
L2FRAG -- AX25 Layer 2 Fragmentation.
DESCRIPTION
Data originated by XRouter is always packaged into the correct
sized frames for the underlying link. For AX25, this size is
specified by PACLEN, which defines the largest payload of an
information-bearing frame.
However XRouter has no control over the size of NetRom
datagrams originated at other systems, which may be larger
than the PACLEN of the AX25 L2 link onto which they are to be
routed.
To cope with this situation, XRouter includes a layer 2
fragmentation scheme, which (if enabled) breaks the datagram
into two or more PACLEN (or smaller) chunks. This scheme is
only used for connected-mode AX25 (LAPB). It supersedes an
earlier NetRom-specific fragmentation scheme which appears to
be no longer used.
A fragmented datagram is indicated by the presence of a
2-byte PID (Protocol Identifier) field in place of the usual
single-byte field. The first byte has the decimal value 8,
indicating that a second PID byte follows. The second byte
indicates how many segments (up to 127) remain to be sent.
The first segment is indicated by the value 128, and the last
segment by 0, i.e. no fragments left.
Whether or not XRouter uses fragmentation is controlled by
bit 4 of CFLAGS (decimal 16). If this bit is set, XRouter
fragments outgoing datagrams if necessary. If the flag is
not set, datagrams are sent unfragmented. This flag should
only be set if the peer is known to be capable (xNOS systems
usually are).
If a fragmented datagram is received from a peer, that peer
is assumed to be capable of fragmentation, and XRouter will
enable fragmentation (and re-assembly of received fragments)
regardless of the setting of bit 4 of CFLAGS.
Compatible Systems
~~~~~~~~~~~~~~~~~~
xNOS and all versions of XRouter are known to be compatible
with this scheme. The status of others such as BPQ32, PE1CHL
Net etc. are unknown at the time of writing (2013). Reports
would be appreciated.
SEE ALSO
CFLAGS(7) -- Connection Control Flags
L3FRAG(9) -- NetRom Layer 3 Fragmentation.
PACLEN(1) -- AX25 Max Packet Length.
L3FRAG
L3FRAG(9) XROUTER REFERENCE MANUAL 16/10/2023
NAME
L3FRAG -- NetRom Layer 3 Fragmentation.
DESCRIPTION
Long ago there was a proposed scheme for fragmenting NetRom L3
datagrams that were larger than the PACLEN of the underlying
AX25 L2 link. This involved breaking large datagrams into
PACLEN (or smaller) fragments, and manipulating bits in the L2
Protocol Identifier (PID), to indicate whether the L2 frame
contained the first, intermediate or last fragment of a NetRom
datagram.
The PID values were as follows:
Hex Dec Meaning
---------------------------------------------
CF 207 First & last (i.e. only) fragment
8F 128 First fragment
4F 64 Last fragment
0F 15 Intermediate fragment.
The scheme was implemented in XRouter, but was not understood
by BPQ, which was a popular node software of the time.
Therefore the code had to be disabled. It is not known which,
if any, modern software implements this scheme.
The fragmentation scheme described above is believed to have
been superseeded by a general-purpose L2 fragmentation scheme
as described in the MAN page entitled L2FRAG.
SEE ALSO
L2FRAG(9) -- AX25 Layer 2 Fragmentation.
PACLEN(1) -- AX25 Max Packet Length.
L3RTT
L3RTT(9) XROUTER REFERENCE MANUAL 7/9/2023
NAME
L3RTT -- Layer 3 Round Trip Time.
DESCRIPTION
L3RTT is an acronym for "Layer 3 Round Trip Time". L3RTT is a
protocol for measuring the round trip time (RTT) of links.
Round trip time is used to estimate the performance of a link.
The smoothed one-way trip time is used in making routing
decisions, and during the automatic estimation of route
QUALITY (Autoqual).
Whilst the layer *2* RTT for a link can be estimated by timing
how long it takes to get an acknowledgement to a given AX25L2
frame, this doesn't tell the full story. The RTT may be good,
yet the link may be experiencing delays simply because there
is too much traffic queued on the link.
L3RTT uses a special type of NetRom layer 3 packet which is
immediately reflected back by the neighbour if it understands
the protocol. This packet is queued with other link traffic,
so it gives a more accurate estimate of the layer 3 RTT at
that moment. The interval between queueing the L3RTT packet
and receiving the returned packet is the layer 3 RTT.
XRouter sends L3RTT packets on already-open neighbour node
links at 5 minute intervals. L3RTT does not open closed
links.
L3RTT frame format:
~~~~~~~~~~~~~~~~~~
Bytes: 7 7 1 1 1 1 1 1 1
.-------.-------.-------.---.---.---.---.---.--------.----.
| l3src | L3dst | l3ttl | 0 | 0 | 0 | 0 | 5 | <text> | CR |
'-------'-------'-------'---'---'---'---'---'--------'----'
<----- L3 Header ------><- Dummy L4header -><- Payload -->
<l3src> is the sender's NODECALL
<l3dst> is L3RTT-0
<L3ttl> is 2 (decremeted to 1 by recipient)
The dummy header simulates L4 <INFO S0 R0>, and the <text>
field is as follows (one space between each field):
6 10 10 10 10 6 11 n n n
<fid> <ts> <srtt> <rtt> <pid> <alias> <id> <vers> <maxt> <flg>
<fid> Frame ID "L3RTT:"
<ts> Time stamp (10ms units)
<srtt> Smoothed Round Trip Time
<rtt> Last round trip time.
<pid> Unique ID for this packet.
<alias> Nodealias of sender.
<id> INP3 version identifier: "LEVEL3_V2.1"
<vers> Software name and version e.g. "XRouter201c"
<maxt> Max trip time (10ms units) e.g. "$M60000"
<flg> Flags field: "$N" indicates INP3 capable
NOTES
The above formatting can no longer be relied upon, as some
faulty 64-bit softwares are overflowing the 10-byte fields!
Some people complain that the L3RTT packets are too long. But
that's the point! They are supposed to simulate typical data
bearing frames. Short packets would give over-optimistic
measurements, and may succeed on poor links where longer
data-bearing packets would be subject to retries.
SEE ALSO
AUTOQUAL(9) -- Automatic Route Quality
QUALITY(1) -- Netrom Route Quality
MENU
MENU(9) XROUTER REFERENCE MANUAL 24/10/2023
NAME
MENU -- Console Pop-up Menu.
DESCRIPTION
Console sysops can access a GUI-style "pop-up" menu at any
time by hitting ALT_M (i.e. pressing the ALT and M keys
together) at any time.
This one-line "main" menu pops up on top of the the second
line of the display, which is usually the title bar for
whichever XRouter "window" is currently being displayed.
At the time of writing the top-level options are "File, View
and Help. The first character of each menu item is
highlighted in red, signifying that it is a "hot-key", i.e.
the menu item can be directly accessed by pressing the
highlighted key. ALT_F, ALT_V and ALT_H directly access the
(F)ile, (V)iew and (H)elp menus respectively.
The left and right arrow keys navigate the top level menu,
highlighting the selected item in white text on a blue
background. As each main memu item is selected, a "drop-down"
sub-menu appears beneath it.
The sub-menus also have "hot-keys" and highlighted items.
The highlight can be moved using the up and down arrow keys,
and the menu item can be actioned using the RETURN key. Or
the item can be directly actioned using the hot key.
For example, there are 3 ways to save the nodes table using
this menu system:
Firstly, ALT_M displays the main menu, where you can use the
left or right arrow keys to select the (F)ile menu, the up
and down arrow keys to select (S)ave nodes, then hit RETURN
to perform the action.
The second method is to use ALT_F to display the (F)ile menu,
then select (S)ave Nodes using the up and down arrows and
RETURN key as before.
The third method is simply to use ALT_F followed by S.
This menu system is a forgotten work in progress, still a
very long way from completion. Feedback and suggestions are
always welcome.
OPTIONS
ALT+M Top level menu
ALT+F (F)ile menu
(R)eload IP routes
(S)ave nodes table
E(X)it program
ALT+H (H)elp menu
(A)bout XRouter
(H)elp Topics
(M)anual Topics
(I)nfo Topics
(C)onfig Info
ALT+V (V)iew menu
C(L)ear Window
S(Y)sop Chat
(C)hat Monitor
(S)ession Monitor
(N)odes Monitor
(R)outes Monitor
(X)router Status
Sec(U)rity Monitor
Console (1)
Console (2)
Console (3)
The (H)elp, (M)an and (I)nfo Topics options display lists of
the available topics. The lists can be navigated using the
arrow keys, and the topic can be viewed in a scrollable
window by hitting RETURN on the highlighted topic.
NOTE
On the Windows version (XR32), the menu is accessed simply by
tapping the ALT key, but this is not possible on Linux
because Linux terminals don't produce a keycode when the ALT
key is pressed by itself.
MHEARD
MHEARD(9) XROUTER REFERENCE MANUAL 18/10/2023
NAME
MHEARD -- "Monitor Heard".
DESCRIPTION
MHEARD is another legacy command name from early TNC days.
The MHEARD facility lists recently heard stations, and may be
enabled or disabled for any port. It records callsigns in
reverse order of reception, with the most recent at the top of
the list, along with other useful information, such as the
date/time, position, type, and the number of frames heard.
This allows sysops and users alike to discover who else the
node can hear, to aid the search for suitable digipeaters, and
to diagnose problems.
Even on linking-only ports, where there is only usually one
partner, it provides a useful indication when the frequency
is being encroached upon, either by deliberate squatting,
unauthorised attempts to link, or lift conditions.
It is therefore recommended that you enable MHEARD on all
ports, and indeed this is the default. The ability to disable
MHEARD (to save memory) was necessary in DOS XRouter, but
memory is not an issue in Windows and Linux versions.
If you have set your LOCATOR, or have included an APRS-style
position report in your ID beacon, XRouter will know its own
position and will display position, distance and bearing for
any stations which broadcast APRS positions. This is a great
aid to network mapping, and it would be nice if everyone were
to add APRS positions to their ID beacons.
If a station was heard via a digipeater, the digipeater call
is also shown, and the letter "D" is shown in the "type"
field. If the heard station is a node, the letter "N" is
displayed. If it is sending IP traffic, "I" is shown, and if
it is sending ARP traffic, "A" is shown.
Within XROUTER.CFG, the "MHEARD=n" directive is used in each
PORT definition block to enable or disable the MHEARD facility
and to set the size of the list. For example "MHEARD=50",
enables it and sets the table size to record a maximum of 50
callsigns. If the directive is omitted, the default size is
15 callsigns.
You can control which types of station are recorded in the MH
list using the "MHFLAGS=n" directive in XROUTER.CFG, or by
using the MHFLAGS command during run-time. The default value
for n is 255 (show everything), and the number is formed by
adding numbers representing the desired options as follows:
1 Record directly heard stations
2 Record directly heard digipeaters
4 Record digipeated stations
8 Record direct/digipeated separately for each station
16 Preserve MHeard list across reboot
For example "MHFLAGS=3" would show directly heard stations and
digipeaters, but not the stations heard via digipeaters.
If the "Preserve MHeard lists across reboot" option is set,
the PORTs MHEARD list is saved to disk at exit and re-loaded
at startup. The list is also saved at regular intervals.
A port's mheard list may be cleared by using the
"MHCLEAR <port-number>" command. You may clear all MH lists
by specifying port 0.
The MHEARD list is available to sysops and users alike, using
the MH command (see command reference section).
SEE ALSO
DX(1) -- DX list.
J(1) -- Recent Sessions.
MHCLEAR(1) -- Clear MHeard list.
MHEARD(1) -- Display recently heard stations.
MHFLAGS(7) -- Set MHeard options.
MHSIZE(1) -- Adjust size of MHeard list.
MHEARD(7) -- MHeard size/enable directive
XROUTER.CFG(8) -- Main Configuration File.
MH-SVC
MH-SVC(9) XROUTER REFERENCE MANUAL 22/9/2023
NAME
MH-SVC -- NetRomX MHeard Service.
DESCRIPTION
The MHEARD service uses NetRomX service number 26. It is
normally used by the "MHEARD <nodecall>" function.
It is not intended for direct connection by humans, but such
operation is possible, as described below:
Upon connection to service 26, the user must send a valid
MHEARD command, such as "MH 0" to list the ports on which
MHeard is available, or "MH 16" to obtain the MH list for
port 16. Only MHeard commands are accepted, any other
command will cause disconnection.
The connection is terminated by the server when the transfer
is complete.
It would be possible for automated network crawlers to use
this feature for harvesting MHeard lists, using the data for
example to build a map showing who can hear whom.
SEE ALSO
DX-SVC(9) -- NetRomX DX List Service.
SERVICES(9) -- NetRomX Standard Services.
MOD128
MOD128(9) XROUTER REFERENCE MANUAL 18/10/2023
NAME
MODULO128 -- AX25 Modulo-128.
DESCRIPTION
Modulo-128 is an extension to AX25, with sequence numbers
from 0 to 127 instead of the usual 0 to 7. This allows a
much bigger MAXFRAME (up to 63) to be used, and is primarily
of use on good links.
On conventional (Modulo-8) AX25 links, much of the
inter-node traffic consists of short frames containing level
4 control information. These frames are interspersed with
data-bearing frames, which themselves may be only partially
full. Thus a router may transmit 7 frames in one go, but
the transmission may only be a few hundred bytes in total.
This is inefficient, due to the delays associated with
channel access, TXDELAY, TXTAIL, RESPTIME etc. On fast,
error-free links the data arrives in short bursts, separated
by long gaps of inactivity.
With Modulo-128, many more frames can be packed into a
single transmission, so the channel overheads become less
significant.
Because the largest allowed MAXFRAME value for Modulo-128
is 63, there can never be any sequence number ambiguity, and
this allows frame "re-sequencing", or "selective reject".
With normal AX25, if the first frame of a multi-frame set is
lost, the whole set of frames must be re-transmitted.
If Modulo-128 is used however, the "good" frames are stored
by the recipient, and only the lost frame is re-sent.
Together with the stored frames, this completes the set, and
the whole set can be acked. This is a much more efficient
strategy.
XRouter is capable of both Modulo-128, and frame
resequencing.
Modulo-128 frames are displayed on the trace screen as
"EAX25" (Extended AX25) instead of "AX25", and are initiated
by a new frame type "SABME" (Set Asynchronous Balanced Mode
Extended). You will notice the sequence numbers being
displayed as "<I R25 S32>"
The method of activation isn't fully decided as yet. If a
caller requests Modulo-128 (by sending an SABME frame),
XRouter will respond with <UA> and go into Modulo-128 mode.
The strategy for outgoing links is more complex. If the
port MAXFRAME is greater than 7, *ALL* level 2 downlinks on
that port will be tried using Modulo-128 (i.e. XRouter will
send <SABME> instead of <SABM>. This is not on user ports,
since hardly any users are EAX25 compatible.
If the called system is Modulo-128 capable, the correct
response to <SABME> is <UA>, otherwise the correct response
according to the AX25 protocol is either <DM> or <FRMR>,
which will cause XRouter to fall back to normal Modulo-8
AX25.
Most systems do answer correctly, but there may however be
some systems which do not properly implement AX25, for
example by silently discarding <SABME> frames, and it will
not be possible to link to these systems if MAXFRAME is
greater than 7. This may be addressed in a future version.
It is more likely that Modulo-128 would be used on
inter-node links with other XRouters, Linux and PE1CHL nodes,
so to activate it, simply define a MAXFRAME > 7 for those
routes which require it. If the port is dedicated to one
link, you can set the port MAXFRAME > 7 instead.
SEE ALSO
ROUTES(1) -- NetRom Route commands.
MAXFRAME(7) -- Maximum Unacked AX25 Frames Directive.
XROUTER.CFG(8) -- Main Configuration File.
MQTT-BLOG
MQTT-BLOG(9) XROUTER REFERENCE MANUAL 26/9/2023
NAME
MQTT-BLOG -- MQTT Interface to Sysop's Blog.
DESCRIPTION
The sysop's blog may be operated via XRouter's inbuilt MQTT
broker, and/or via an external broker, by subscribing or
publishing to certain topics.
This facility is incomplete. The curently available
functionality is documented in the next section.
OPTIONS
a) Receive Notifications of Blog Events:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Topic: xrouter/event/{nodecall}/blog
The payload of an event notification is an un-named JSON
object containing the following fields:
Name Type Description
-----------------------------------------------------------
"id" integer Article/post number.
"rcvd" string Date/time of message creation (*).
"size" integer Length of the blog text in bytes.
"from" string Callsign of the post's creator.
"subject" string Topic of the post (32 chars max)
"text" string Body of the post (plain ASCII)
"event" string Type of event ("posted" or "deleted")
(*) in format "1997-09-14T23:47:00Z"
b) Retrieve a Blog Post:
~~~~~~~~~~~~~~~~~~~~~~~~
Topic: xrouter/get/{nodecall}/blog/msg/{msgnum}
The response payload is an un-named JSON object containing
the following fields:
Name Type Description
-----------------------------------------------------------
"id" integer Article/post number.
"rcvd" string Date/time of message creation (*).
"size" integer Length of the blog text in bytes.
"from" string Callsign of the post's creator.
"subject" string Topic of the post (32 chars max)
"text" string Body of the post (plain ASCII)
(*) in format "Mon, 14 Sep 1997 23:47:00 GMT"
c) Post a Blog Article / Reply:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Topic: xrouter/put/{nodecall}/blog
The payload must be a JSON object containing the following
fields:
Name Type Description
-----------------------------------------------------------
"sender" string Callsign of sender
"replyto" integer No. of msg being replied to (0=new)
"subject" string Subject of the post (32 chars max)
"text" string Body of the post (unlimited size)
Response: None unless QOS > 0
LIMITATIONS
The blog's MQTT interface does not yet notify "like" events,
nor does it allow article listings, deletion, "liking", or
the retrieval of replies. Those functions will be added in a
future version
SEE ALSO
BLOG(1) -- Access Sysop's Blog.
BLOGFLAGS(7) -- Options For Sysop's Blog.
REST-BLOG(9) -- REST Interface to Blog.
MQTT-CLI(9) -- MQTT Client
MQTT-SRV(9) -- MQTT Server / Broker.
MQTT-CHAT
MQTT-CHAT(9) XROUTER REFERENCE MANUAL 26/9/2023
NAME
MQTT-CHAT -- MQTT Interface to Chat Server.
DESCRIPTION
The chat server may be operated via XRouter's inbuilt MQTT
broker, and/or via an external broker, by subscribing or
publishing to certain topics.
This facility is incomplete. The curently available
functionality is documented in the next section.
OPTIONS
a) Receive Notifications of Chat Events:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These events are published by XRouter whenever someone
joins or leaves a channel, changes name, personal text or
channel topic, or sends a nmessage.
Subscribe Topic: xrouter/event/{nodecall}/chat/{event-type}
Event-types are:
join User joins a channel
leave User leaves a channel
name User sets or changes name
pers User sets or changes personal text
topic User sets or changes channel topic
msg User sends a chat message
The payload of an event notification is an un-named JSON
object containing the following fields:
Name Type Description
-----------------------------------------------------
"user" string Callsign of user
"host" string Alias of chatserver the user is on
"name" string User's name
"time" string Time of event in form HH:MM
"channel" number Channel number (*1)
"topic" string Topic name for channel (*2)
"pers" string Personal text (*3)
"reason" string Reason for leaving channel (*4)
(*1) "channel" not present in "name" or "pers" events
(*2) "topic" only present in "topic" events
(*3) "pers" only present in "pers" events
(*4) "reason" only present in "leave" events
Internally the event time is stored as a 32bit unsigned
integer, representing the number of seconds since 1/1/70. It
could be sent as a number instead of a string, if that was
easier for the consuming client?
Channel numbers can range from -32767 to +32767. Negative
channels are used for Tampa Ping Pong chat. Channel 101 is
BPQ (W0RLI's RoundTable) chat. Channel numbers between 0 and
999, except 101, are local only. Channels > 999 are
distributed to all XRChat servers.
b) List Chatserver Channels and Users:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If the client publishes a "get" request, XRouter responds by
publishing the requested data to a similar "status" topic.
Request Topic: xrouter/get/{nodecall}/channels
Response Topic: xrouter/status/{nodecall}/channels
The response payload is a JSON array, which may be empty. If
present, each array element (channel) has at least the
following fields:
Name Type Description
----------------------------------------------------
"number" number Channel number (-32767 to 32767)
"topic" string Channel topic, e.g. "RoundTable"
"users" array List of users on the channel
The "users" array may be empty. If any users are present, a
user array element contains the following fields:
Name Type Description
----------------------------------------------------
"user" string User ID (usually callsign)
"host" string Alias of their chat server
"name" string User's name
"idle" string Elapsed time since activity
"stat" string Short presence/status text
"pers" string Personal text
"qth" string Home town
Some fields may be empty, e.g. personal text and QTH.
Idle time is "0s" to "59s", then "1h" to "23h", then "1d"
upwards.
Short presence/status codes are:
"Offline" Not on chat
"Avail" Available to chat
"Busy" Possibly watching, but likely too busy to reply
"BRB" Be Right back - very short break
"Away" Away from computer for a while
"Lunch" Out to lunch
"Phone" On the phone, will be back
"D.N.D" Do Not Disturb. Don't involve me
"Asleep" Gone to bed, so not watching live
"In&Out" Reading and responding intermittently
Example:
pub xrouter/get/G8PZT-1/channels
xrouter/status/G8PZT-1/channels
[
{
"number": 101,
"topic": "RoundTable",
"users": [
]
},
{
"number": 1000,
"topic": "Welcome",
"users": [
"user": "G8PZT-4",
"host": "MOBCHT",
"name": "Paula",
"idle": "1m",
"stat": "Avail,",
"pers": "Programming again!"
"qth": "kidderminster"
]
},
{
"number": 1234,
"topic": "Sysop Chat",
"users": [
]
}
]
c) Post a Chat Message:
~~~~~~~~~~~~~~~~~~~~~~~
Publish Topic: xrouter/put/{nodecall}/chat
The payload must be a JSON object containing the following
fields:
Name Type Description
------------------------------------------------------
"sender" string Callsign of sender
"channel" number Destination channel
"name" string Sender's name
"text" string Body of the message
Channel numbers can range from -32767 to +32767. Negative
channels are used for Tampa Ping Pong chat. Channel 101 is
BPQ (W0RLI's RoundTable) chat. Channel numbers between 0 and
999, except 101, are local only. Channels > 999 are
distributed to all XRChat servers.
Response: None unless QOS > 0
LIMITATIONS
The chat MQTT interface is only a proof-of-concept at this
stage, and some details may change. More functionality will
be added in a future version.
SEE ALSO
CHAT(1) -- Connect to Chat Server.
CHAT-SRV(9) -- About the chat server.
MQTT-CLI(9) -- MQTT Client
MQTT-SRV(9) -- MQTT Server / Broker.
MQTT-PMS
MQTT-PMS(9) XROUTER REFERENCE MANUAL 26/9/2023
NAME
MQTT-PMS -- MQTT Interface to Personal Message System.
DESCRIPTION
The PMS may be operated via XRouter's inbuilt MQTT
broker, and/or via an external broker, by subscribing or
publishing to certain topics.
This facility is incomplete. The curently available
functionality is documented in the next section.
OPTIONS
a) Receive Notifications of PMS Message Events:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These events are published by XRouter whenever someone
creates, reads, or kills a message, and when a message is
delivered to the recipient's PMS.
Subscription Topic: xrouter/event/{nodecall}/pmsg
The payload of an event notification is an un-named JSON
object containing the following fields:
Name Type Description
-----------------------------------------------------
"number" integer Message number.
"mid" string Message ID (MID or BID)
"rcvd" string Date/time of message reception (*1).
"size" integer Length of the message body in bytes.
"type" string Type of message: (A, P, B, E, T etc)
"status" string Message status: (R, F, U etc) (*2)
"to" string Destination address (*3)
"from" string Callsign of the message's creator.
"subject" string Message subject (32 chars max)
"event" string Event type (*4)
(*1) in format "1997-09-14T23:47:00Z"
(*2) type and status may in future be unambiguous words
(*3) e.g. "g8pzt", "all@gbr", "g8pzt@gb7pzt.#24.gbr.eu"
(*4) event types are as follows:
"newmsg" New message
"fwded" Message has been forwarded
"read" Message has been read
"killed" Message has been killed
Example:
{
"number": 117,
"mid": "47DCE8A17PZT"
"size": 67,
"type": "P",
"to": "G8PZT@DOTPMS",
"from": "G9DUM",
"subject": "test 1",
"event": "newmsg"
}
b) Retrieve a Message:
~~~~~~~~~~~~~~~~~~~~~~
Publish Topic: xrouter/get/{nodecall}/mail/msg/{msgnum}
The response payload is an un-named JSON object containing
the following fields:
Name Type Description
-----------------------------------------------------
"number" integer Message number.
"mid" string Message ID (MID or BID)
"rcvd" string Date/time of message reception (*1).
"size" integer Length of the message body in bytes.
"type" string Type of message: (A, P, B, E, T etc)
"status" string Message status: (R, F, U etc) (*2)
"to" string Destination address (*3)
"from" string Callsign of the message's creator.
"subject" string Message subject (32 chars max)
"text" string Body of the message (*4)
(*1) in format "1997-09-14T23:47:00Z"
(*2) type and status may in future be unambiguous words
(*3) e.g. "g8pzt", "all@gbr", "g8pzt@gb7pzt.#24.gbr.eu"
(*4) Message body includes all RFC822 and routing headers
c) Post a Message:
~~~~~~~~~~~~~~~~~~
Publish Topic: xrouter/put/{nodecall}/mail
The payload must be a JSON object containing the following
fields:
Name Type Description
------------------------------------------------------
"from" string Callsign of sender
"to" string Destination (see below)
"type" string Only "P" or "B" at present
"subject" string Subject of message (32 chars max)
"text" string Body of the message
For private messages the destination may be just a callsign,
or <callsign>@<hierarchical-address>. For bulletins it may
be simply <topic> or <topic>@<distribution>. For email it is
<user>@<host>.
Response: None unless QOS > 0
LIMITATIONS
The PMS's MQTT interface is only a proof-of-concept at this
stage, and some details may change. More functionality will
be added in a future version.
SEE ALSO
PMS(1) -- Access Personal Message System.
PMS(9) -- About the Personal Pessage System.
REST-PMS(9) -- REST Interface to PMS.
MQTT-CLI(9) -- MQTT Client
MQTT-SRV(9) -- MQTT Server / Broker.
MQTT-PUB
MQTT-PUB(9) XROUTER REFERENCE MANUAL 23/9/2023
NAME
MQTT-PUB -- MQTT Publisher.
DESCRIPTION
The MQTT "publisher" is an inbuilt MQTT client daemon which,
if enabled, automatically connects to an *external* MQTT
broker (server), and publishes data to it. The broker may be
on the LAN or in the cloud.
The broker's IP address or hostname is specified using
MQTTSERVADDR in XROUTER.CFG, and its TCP port number by
MQTTSERVPORT, which defaults to 1883. If the broker address
is not specified (the default condition), or the broker port
is set to 0, the publisher is disabled.
If enabled, various information is sent to the broker in JSON
format, including station configuration, layer 2, 4 and 7
events such as connections and disconnections, radio control
events such as PTT, frequency and mode changes, PMS message
events, chat server events, raw packet data and so on. As
proof of concept, a web-based chat server interface has been
demonstrated.
The term "publisher" is somewhat of a misnomer, as the data
flow is bi-directional.
Therefore any client of the external broker may not only
passively receive "pushed" data from XRouter, but may also
"push" data to XRouter, and "pull" data from it on request.
By publishing to "getter" topics, a client may request status
reports, such as lists of AX25 L2 links, routes, nodes, L4
circuits, sessions, recent sessions, chat server status,
MHeard and DX lists etc.
By publishing to "putter" topics, a client may also send data
to the node, such as chat, PMS and control mesages, raw
packet data etc. Ulitmately it should be possible to provide
a full MQTT-based interface to packet radio.
See MQTT-SRV(9) for the list of getter and putter topics.
SEE ALSO
MQTT-CLI(9) -- MQTT Client
MQTT-SRV(9) -- MQTT Server / Broker
MQTT-SVC(9) -- NetRomX MQTT Service
MQTTSERVADDR(7) -- Hostname / IP of Externam MQTT Broker
MQTTSERVPORT(7) -- TCP Port for External MQTT Broker
XROUTER.CFG(8) -- Main Configuration File.
MQTT-SRV
MQTT-SRV(9) XROUTER REFERENCE MANUAL 23/9/2023
NAME
MQTT-SRV -- MQTT Server / Broker.
DESCRIPTION
XRouter has an inbuilt MQTT broker (server), which allows
MQTT clients to exchange information with XRouter, with each
other, and with an external broker.
The broker may be enabled on XRouter and/or Linux IP stacks
using the MQTTPORT directive in XROUTER.CFG. The usual TCP
port number for MQTT is 1883.
Although primarily intended for use via the LAN, the broker
is also available via NetRomX service 1883 for anyone who
wants to experiment with MQTT over radio.
Clients may "publish" data to "topics", and may "subscribe"
to topics, in order to receive any data published to that
topic.
XRouter automatically publishes "events", both to the
internal MQTT broker, and if configured to do so, to an
external broker.
The information, which is published in JSON format, includes
station configuration, layer 2, 4 and 7 events such as
connections and disconnections, radio control events such as
PTT, frequency and mode changes, PMS message events, chat
server events, raw packet data and so on. As proof of
concept, a web-based chat server interface has been
demonstrated.
A client may also request status reports, such as lists of
AX25 L2 links, routes, nodes, L4 circuits, sessions, recent
sessions, chat server status, MHeard and DX lists etc.
A client may also send information to the node, such as chat,
PMS and control mesages. Ultimately it should be possible to
provide a full MQTT-based interface to packet radio. That bit
is left up to you!
OPTIONS
Subscription Topics:
~~~~~~~~~~~~~~~~~~~~
Subscribing to any of the following topics causes XRouter to
publish data asynchronously, to the same topic:
xrouter/event/{nodecall}/blog Sysop's Blog Events
xrouter/event/{nodecall}/chat/{evtype} Chat Events
xrouter/event/{nodecall}/circuit NetRom L4 Cct Events
xrouter/event/{nodecall}/link AX25 Link Events
xrouter/event/{nodecall}/pmsg PMS Message Events
xrouter/event/{nodecall}/radio/{number} Radio Events
xrouter/event/{nodecall}/session Session Layer Events
xrouter/event/{nodecall}/wall Message "wall" Events
xrouter/event/{nodecall}/wx[/{call}] Weather data events
xrouter/ax25/{nodecall}/rcvd/{portnum} Raw AX25 Frames Rx'd
xrouter/ax25/{nodecall}/sent/{portnum} Raw AX25 Frames Tx'd
xrouter/ipv4/{nodecall}/rcvd Raw IPV4 Frames Rcvd
xrouter/ipv4/{nodecall}/sent Raw IPV4 Frames Sent
xrouter/kiss/{nodecall}/rcvd/{ifacenum} KISS Frames Received
xrouter/kiss/{nodecall}/sent/{ifacenum} KISS Frames Tx'd
xrouter/nr3b/{nodecall}/rcvd Netrom Traffic Rx'd
xrouter/nr3b/{nodecall}/sent Netrom Traffic TX'd
Getter Topics:
~~~~~~~~~~~~~~
These are used to obtain information *from* XRouter on demand.
Publishing to any of these topics elicits a reply from
XRouter, with "get" replaced by "status" in the topic:
xrouter/get/{nodecall}/blog/msg/{msgnum} Retrieve a blog post
xrouter/get/{nodecall}/channels Chat channel occupancy
xrouter/get/{nodecall}/circuits Netrom L4 circuits
xrouter/get/{nodecall}/config Node Configuration Info
xrouter/get/{nodecall}/jlist Recent Sessions
xrouter/get/{nodecall}/links AX25 circuits
xrouter/get/{nodecall}/mheard Port "MHeard" Lists
xrouter/get/{nodecall}/nodes NetRom Nodes Table
xrouter/get/{nodecall}/node/{call} Info For Specific Node
xrouter/get/{nodecall}/recent Recent chat messages
xrouter/get/{nodecall}/routes NetRom Neighbour Routes
xrouter/get/{nodecall}/users Current Sessions
xrouter/get/{nodecall}/wall/msg/{msgnum} Retrieve a wall post
Putter Topics:
~~~~~~~~~~~~~~
These are used to send information *to* XRouter. They don't
elicit any response, other than a PUBACK if QOS > 0.
xrouter/put/{nodecall}/ax25/{portnum} Send raw AX25 (*1)
xrouter/put/{nodecall}/blog Post a blog article
xrouter/put/{nodecall}/chat Send a CHAT message
xrouter/put/{nodecall}/ipv4 Send raw IP datagram
xrouter/put/{nodecall}/kiss/{ifacenum} Send raw KISS Frame
xrouter/put/{nodecall}/nr3b Send raw NetRom (*2)
xrouter/put/{nodecall}/wall Post a wall message
xrouter/put/{nodecall}/wx Post local weather data
(*1) Without HDLC framing or CRC
(*2) Routable datagrams only, no L3RTT, INP3 or Nodes bcasts!
CAVEATS
This system is by no means finished. There's a lot more that
could be done, but it needs someone to actually USE it and
provide feedback.
SEE ALSO
MQTT-BLOG(9) -- MQTT Interface to Sysop's Blog.
MQTT-CLI(9) -- MQTT Client
MQTT-SVC(9) -- NetRomX MQTT Service.
MQTT-PUB(9) -- MQTT Publisher.
MQTT-WALL(9) -- MQTT Interface to Message Wall.
MQTTPORT(7) -- TCP Port for MQTT Broker.
XROUTER.CFG(8) -- Main Configuration File.
MQTT-SVC
MQTT-SVC(9) XROUTER REFERENCE MANUAL 22/9/2023
NAME
MQTT-SVC -- NetRomX MQTT Broker Service.
DESCRIPTION
NetRomX service 1883 connects to XRouter's inbuilt MQTT
broker, allowing MQTT over NetRom for anyone who wants to
experiment.
This may be a bad idea, but we don't know until we give it
a go!
It may be that we have to restrict the types of data that
can be sent and received, to avoid death-loops.
SEE ALSO
MQTT-PUB(9) -- MQTT Publisher.
MQTT-SRV(9) -- MQTT Server / Broker
SERVICES(9) -- NetRomX Standard Services
MQTT-WALL
MQTT-WALL(9) XROUTER REFERENCE MANUAL 26/9/2023
NAME
MQTT-WALL -- MQTT Interface to Message Wall.
DESCRIPTION
The message "wall" may be operated via XRouter's inbuilt MQTT
broker, and/or via an external broker, by subscribing or
publishing to certain topics.
This facility is incomplete. The curently available
functionality is documented in the next section.
OPTIONS
a) Receive Notifications of Wall Events:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Topic: xrouter/event/{nodecall}/wall
The payload of an event notification is an un-named JSON
object containing the following fields:
Name Type Description
-----------------------------------------------------------
"id" integer Article/post number.
"rcvd" string Date/time of message creation (*).
"size" integer Length of the text portion in bytes.
"from" string Callsign of the post's creator.
"text" string Body of the post (plain ASCII)
"event" string Type of event ("posted" or "deleted")
(*) in format "Mon, 14 Sep 1997 23:47:00 GMT"
b) Retrieve a Wall Post:
~~~~~~~~~~~~~~~~~~~~~~~~
Topic: xrouter/get/{nodecall}/wall/msg/{msgnum}
The response payload is an un-named JSON object containing
the following fields:
Name Type Description
-----------------------------------------------------------
"id" integer Article/post number.
"rcvd" string Date/time of message creation (*).
"size" integer Length of the text in bytes.
"from" string Callsign of the post's creator.
"text" string Body of the post (plain ASCII)
(*) in format "Mon, 14 Sep 1997 23:47:00 GMT"
c) Post a Wall Message / Reply:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Topic: xrouter/put/{nodecall}/wall
The payload must be a JSON object containing the following
fields:
Name Type Description
-----------------------------------------------------------
"sender" string Callsign of sender
"text" string Body of the post (unlimited size)
Response: None unless QOS > 0
LIMITATIONS
The wall's MQTT interface does not yet notify "like" events,
nor does it allow article listings, deletion, "liking", or
the retrieval of replies. Those functions will be added in a
future version
SEE ALSO
WALL(1) -- Access Message Wall / Guestbook.
WALLFLAGS(7) -- Options For Message Wall.
REST-WALL(9) -- REST Interface to Wall.
MQTT-SRV(9) -- MQTT Server / Broker.
MQTT-WX
MQTT-WX(9) XROUTER REFERENCE MANUAL 26/9/2023
NAME
MQTT-WX -- MQTT Interface to Weather System.
DESCRIPTION
If XRouter has a source of weather information, e.g. APRS
broadcasts, local sensors or an online source, weather updates
can be received from XRouter's inbuilt MQTT broker by
subscribing to the "weather events" topic, i.e.
xrouter/event/{nodecall}/wx
Weather data stored on XRouter can also be retrieved at any
time using MQTT "get" requests.
A "get" request is an MQTT "publish" packet with a topic of
the general form:
xrouter/get/{nodecall}/{resource}
Such requests are actioned directly by XRouter and are NOT
published to other clients.
The response from XRouter is published to a topic of the
general form:
xrouter/status/{nodecall}/{resource}
The response payload is either a JSON object or a JSON array,
depending on the requested resource.
The response is sent only to the client making the request.
There are curently two possible {resource} types, namely the
"station ID" of a weather station, or "allwx". Station ID's
are usually callsigns, but may take other forms such as
"LOCAL", "SHED", "SHACK" and so on.
LOCAL is the primary resource for locally sourced weather
information. Unlike the other resources it maintains max/min
values and times, trends and so on.
Weather information can also be uploaded to XRouter from a
local source (e.g. RTL_433), via the MQTT server.
OPTIONS
a) Receive Notifications of Weather Reports:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Subscribe Topic: xrouter/event/{nodecall}/wx
The payload of a weather event is an un-named JSON object
containing some or all of the following fields:
Name Type Description
-----------------------------------------------------------
"id" string Station id, e.g. "G8PZT" or "LOCAL"
"lat_deg" number Latitude of WX station in degrees
"lon_deg" number Longitude of wx station in degrees
"dist_km" number Distance from our node in kilometres
"dir_deg" number Direction from our node in degrees
"dt" integer Observation time, secs since 1/1/70
"observed" string Date and time of observation (*1)
"pressure_mb" number Air pressure in millibars
"temperature_C" number Air temperature in degrees C
"humidity" number Relative Humidity in percent
"dewpoint_C" number Dew point in degrees Centigrade
"heat_index_C" number Heat index in deg Centigrade
"wind_chill_C" number Wind Chill in degrees Centigrade
"wind_mph" number Wind speed in miles per hour
"wind_dir_deg" number Wind direction in degrees
"gust_mph" number Wind gust speed in miles per hour
"raintoday_mm" number Total rain since midnight in mm
"rain1h_mm" number Current rainfall rate mm/hour
"rain24h_mm" number Total rain in past 24 hours in mm
"sunrise" string Sunrise time at the station hh:mm
"sunset" string Sunset time at the station hh:mm
"daylight_hours" number Hours between sunrise and set
(*1) As "dt" but human-readable e.g. 2024-03-14T15:19:59Z
b) Requesting Weather Data From a Specific Station:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Publish Topic: xrouter/get/{nodecall}/wx/{station_id}
Reply topic: xrouter/status/{nodecall}/wx/{station_id}
The reply payload is an anonymous JSON object, containing
the fields detailed in section (a) above.
c) Requesting All Available Weather Data:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Publish Topic: xrouter/get/{nodecall}/allwx
Reply topic: xrouter/status/{nodecall}/allwx
The reply payload is an anonymous JSON array, containing zero
or more JSON objects. Each object, representing one weather
station, contains the fields detailed in section (a) above.
d) Uploading Weather Data To XRouter:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Publish Topic: xrouter/put/{nodecall}/wx
Payload: JSON object containing weather data.
The exact format of the payload is configurable by the sysop,
to match the fields used by the originating MQTT source. The
default values as as follows:
Name Type Description
--------------------------------------------------------
"model" string Sensor make/model
"id" string Sensor identifier
"time" string Observation time (mandatory) (*1)
"pressure" number Air pressure in millibars
"temperature_c" string Air temperature in degrees C (*2)
"humidity" integer Relative humidity in percent
"wind_avg_m_s" string Wind speed in metres per sec (*3)
"wind_max_m_s" string Gust speed in metres per sec (*3)
"wind_deg" string Wind direction in degrees (*4)
"rain_mm" string Total rainfall in mm (*5)
"light_lux" string Solar Irradiance in lux (*6)
"uv" integer UV level
"uvi" integer UV Index
"battery_ok" integer Sensor battery indication
(*1) Observation time is mandatory. Acceptable formats are
Unix epoch (i.e. secs since 1/1/1970), a date/time like
"yyyy-mm-dd hh:mm:ss", or "yyyy-mm-ddThh:mm:ssZ". e.g.
"2024-03-14T15:19:59Z".
(*2) Temperature defaults to centigrade, unless the value
string is suffixed by the letter "F" (case independent).
If the value contains a decimal point, it is assumed to
be in degrees. If there is no decimal point, it
signifies tenths of a degree. In this mode, negative
temperatures using either 12-bit or 16-bit "two's
complement" are accepted.
e.g. "10.1" and "101" both mean 10.1 degrees Centigrade.
"50.5F or "505 F" or "50.5 f" all mean 50.5 degrees
Fahrenheit. "65540" means -1.5 degrees Centigrade if the
sensor is using 16-bit two's complement.
(*3) Wind speeds default to miles per hour if no units are
present in either the field name or the value string.
If the field name contains "m_s" or the value string
contains "m/s", the units are metres per second.
If the field name contains "km_h" or the value string
contains "km/h" the units are kilometres per hour.
(*4) Wind direction may be specified in whole degrees (0-359),
or as cardinal points, e.g. "N", "W", "SSE" etc.
(*5) If the field name contains "mm" or the value contains a
decimal point, the rainfall units are assumed to be
millimetres, otherwise they are assumed to be cumulative
"bucket tips". The default bucket size of 0.3mm, can be
changed using the WXBUCKET directive in XROUTER.CFG.
(*6) Light level defaults to watts per square metre, but can
be specified in Lux by appending "lux", e.g. "4568 lux".
The uploaded data is assumed to be from a local sensor, and
is therefore stored under the station ID "LOCAL". Future
versions may allow for extra sensors, as per the REST API.
EXAMPLES
xrouter/event/G8PZT/wx - Get weather notifications
xrouter/get/G8PZT/wx/G6GUH-7 - Retrieve WX data from G6GUH-7
xrouter/get/G8PZT/allwx - Retrieve all weather data
SEE ALSO
WX(1) -- Display Weather Information.
WX(9) -- Weather Information System.
REST-WX(9) -- REST Interface to Weather System.
MQTT-SRV(9) -- MQTT Server / Broker.
NAT
NAT(9) XROUTER REFERENCE MANUAL 17/10/2023
NAME
NAT -- Network Address Translation.
DESCRIPTION
Section 1 - About Network Address Translation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In order for a computer (sometimes called a "host") to
communicate with other computers using TCP/IP it must have an
IP address. This is a 32 bit number unique to that machine,
and it is composed of four 8 bit fields which hosts use to
make routing decisions.
Theoretically, there could be 2**32 unique addresses (just
over 4000 million), but in practice the figure is a lot lower
because some of the addresses are not used. This is due to
the way addresses are separated into classes and assigned to
networks.
For example, the "class A" address series 44.x.x.x is assigned
to the amateur radio network and contains 2**24 (16.7 million)
addresses. Within this series, the series 44.131.x.x is
assigned to the UK, and contains 2**16 (65536) addresses.
Taking this further, the series 44.131.91.x is assigned to
north Worcestershire and contains 2*8 (256) addresses, yet
there are only a couple of IP stations in north
Worcestershire. So the remaining IP addresses are "wasted".
A similar wastage occurs in every county in the UK and every
country in the world.
Although there are only a couple of registered IP stations in
the 44.131.91.x series, each station may be running more than
one computer. Some of these machines are nothing to do with
amateur radio and therefore are not entitled to a 44.x.x.x
series IP address. In addition, registering IP addresses is a
lengthy procedure which is impractical for dealing with a home
network in which computers are rearranged frequently.
In order to cater for these private and experimental networks,
a number of address ranges were set aside for "unregistered"
use. One such series is 192.168.0.x which can cater for up to
256 hosts. Any one of these addresses may be used in millions
of private networks at once, thus alleviating the shortage of
IP addresses.
A problem arises if an "unregistered" host on a private
network needs to communicate with a host on the "registered"
network. Packets from the unregistered (local) host can be
routed to the registered (global) host, but since the local
host is unregistered, and the same address is used many places
at once, the network has no way of knowing where to send the
replies.
This is where Network Address Translation (NAT) comes to the
rescue. NAT operates on each datagram, substituting one IP
address with another.
For instance a local address such as 192.168.0.2 can be
translated to a globally recognised one, such as 44.131.91.2,
allowing a host on a LAN to access, and be visible to, the
global network.
Consider this example:
Registered IP Unregistered IP
44.131.91.2 192.168.0.2
44.131.91.3 192.168.0.16
Packets arriving from the global network addressed to
44.131.91.2 are re-addressed to 192.168.0.2 and routed to the
appropriate machine on the local network, while those
addressed to 44.131.91.3 are re-addressed to 192.168.0.16 and
routed to that machine.
In the reverse direction, packets originating from host
192.168.0.2 on the LAN, destined for the global network, have
their source address changed to the globally recognised
44.131.91.2, and 192.168.0.16 is translated to 44.131.91.3.
This one to one mapping of one address to another is called
STATIC NAT, (also known as RFC1631 NAT) and is implemented in
Xrouter.
Port Address Translation
~~~~~~~~~~~~~~~~~~~~~~~~
With Static NAT, if you have more than one local host which
needs to be visible on the global network, you must own more
than one registered IP address. A refinement of NAT, called
Port Address Translation (PAT) allows one registered IP
address to be shared by many unregistered hosts, by
manipulating the "service port" numbers in TCP and UDP packet
headers.
For example, consider the following mappings:
Global address Port Local address Port
-------------- ---- ------------- ----
44.131.91.2 777 192.168.0.1 1024
44.131.91.2 778 192.168.0.2 1024
44.131.91.2 779 192.168.0.5 1631
TCP segments originating from port 1024 on local host
192.168.0.1, and destined for the global network, are
re-addressed to look like they originated from port 777 on
the globally-recognised host 44.131.91.3. Likewise, segments
from port 1631 on local host 192.168.0.5 are made to look like
they originated from port 779 on global host 44.131.91.2. The
translations are reversed for incoming segments.
PAT can be static or dynamic. With static PAT, the sysop must
set up the translation table as in the example above. Dynamic
PAT builds the table automatically, and the entries are
removed when they're finished with. This makes the two
systems behave very differently, as discussed below.
Static PAT
~~~~~~~~~~
This form of PAT consistently translates a global address/port
pair to an equivalent local address/port pair and vice versa.
Since the mappings are permanent and predictable, the
designated ports on the local hosts are visible to the global
network. This is ideal for making local servers (e.g. SMTP,
HTTP, POP3) globally visible.
Static PAT can be used to multiplex several hosts onto one IP
address, or it can simply be used to manipulate port numbers,
for example to create "virtual hosts" as shown below:
Global address Port Local Address Port
44.131.91.2 80 192.168.0.1 8000
44.131.91.3 80 192.168.0.1 8001
44.131.91.4 80 192.168.0.1 8002
The outside world sees 3 web servers (port 80 is the HTTP
port), with the IP addresses 44.131.91.2, 91.3 and 91.4, yet
in reality there are 3 separate web server processes (ports
8001, 8002, 8003) running on one host.
There is a problem with static PAT however. TCP/IP server
processes use predictable port numbers. For instance, HTTP
servers usually use port 80 (although they can often be
re-configured for a different port), which means that incoming
TCP segments addressed to port 80 will always go to the web
server, and the server will reply using the same port as the
source.
TCP/IP *clients* on the other hand tend to use unpredictable
port numbers. For example, the first Telnet client session on
a freshly booted Windows98 system will use port 1024, the next
session will use port 1025 and so on. With static PAT, set up
to translate port 1024 to an outside world address/port pair,
the first Telnet session will succeed, but the second and
subsequent ones will fail.
Therefore as a general rule, static PAT is useful for making
local SERVERS globally visible, but not for accessing the
global network using local CLIENTS. It's a one way street.
This effect can be exploited to prevent LAN users from
accessing the global network.
Dynamic PAT
~~~~~~~~~~~
Dynamic PAT is commonly used to multiplex several hosts onto
one IP address a process called "Overloading", and it tends to
act as a one way street in the opposite direction to static
PAT.
Translation entries are created when a local host originates a
connection to the global network, and are removed when that
connection is closed. Thus dynamic PAT cannot generally be
used to make local servers globally visible, but outgoing
connections can be made without hindrance.
This creates a simple "firewall", preventing your local hosts
from attacks from the global network.
Both static and overloaded PAT are implemented in XRouter.
Limitations of NAT / PAT
~~~~~~~~~~~~~~~~~~~~~~~~
Unfortunately, NAT and PAT are not completely transparent to
the user, and there are certain situations which they cannot
handle.
IP, ICMP, TCP and UDP packet headers each contain a
"checksum", and the IP addresses and service port numbers are
included in the calculation. This means that any change to the
address or port numbers requires all the checksums to be
recalculated and re-inserted.
In most cases it is sufficient to manipulate the packet
headers alone, but some protocols convey IP address and TCP
port numbers in the data portion of the packet, and these
present more of a problem.
ICMP error reports return part of the faulty datagram, and
that part must be re-translated and the checksums recalculated
if the process is to remain completely invisible to the user.
Certain FTP transactions convey an IP address and port number,
expressed in ASCII, in the data. NAT must look for these and
change them. Besides being a non-trivial operation, the
problem with this is that the translated addresses may occupy
a different amount of space when expressed in ASCII, so NAT
must build a new packet, and must adjust the TCP sequence
numbers on every subsequent packet.
There are other applications which similarly embed addressing
information in the data portion of the packet, and strictly
speaking, the TCP/IP layers must remain unaware of this
information as it is of a higher layer. In this respect NAT
breaks normal layering rules.
PAT achieves multiplexing by translating service port numbers,
but some protocols do not use service port numbers at all, so
these can not pass through PAT. For example, ICMP, IPIP and
AXIP can only pass through static NAT, whereas AXUDP and IPUDP
can pass through PAT.
The following protocols and traffic will pass through NAT:
Protocol Supported Traffic / Applications
-------------------------------------------------
RIP ?
ICMP Ping, Traceroute etc.
AXIP Ax25 tunnelling
IPIP IP tunnelling.
UDP AXUDP, IPUDP, DNS, TFTP
TCP Telnet, HTTP, SMTP, NNTP, POP, Finger, Rlogin
Plus any other traffic which does not use
TCP/IP addresses in the application data.
Only the following protocols / traffic will pass through PAT:
Protocol Supported Traffic / Applications
-------------------------------------------------
UDP AXUDP, IPUDP, DNS, TFTP
TCP Telnet, HTTP, SMTP, NNTP, POP, Finger, Rlogin
Plus any other traffic which does not use
TCP/IP addresses in the application data.
Section 2 - Configuring NAT / PAT on Xrouter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The "NAT" commands are used for configuring both NAT and PAT
on the fly. They can also be embedded in the IPROUTE.SYS or
BOOTCMDS.SYS files to configure the system at startup.
The following commands are available:
NAT ADD Adds entries to the translation table.
NAT DROP Deletes entries from the translation table.
NAT LIST Displays the translation table.
Syntax is as follows:
NAT ADD STATIC <localIP>[:port] <globalIP>[:port] [tcp | udp]
NAT ADD OVERLOAD <localIP> <globalIP> <subnet_mask>
The first form adds static NAT and PAT entries, and the second
form is used only for adding overloaded dynamic PAT entries.
In each case <localaddr> represents the "private" or
"unregistered" IP address of a host on the stub network, and
<globaladdr> represents a globally recognised or "registered"
address.
In the STATIC case, if port numbers are specified, TCP and UDP
traffic matching the specified IP addresses will be translated
ONLY if it also matches the specified ports. If ports are not
specified, all traffic is translated. If the optional
protocol is specified, only traffic of that protocol will be
translated by that entry.
The OVERLOAD case does not accept port numbers, and it
requires a subnet mask to be specified. The mask is used in
combination with the local address to form a range of
addresses which will be accepted for translation. For
example, if the local address is 192.168.0.0 and the netmask
is 255.255.255.240, addresses 192.168.0.0 to 192.168.0.15
inclusive will be translated.
NAT DROP <local>[:port] [tcp | udp]
Simple entries, i.e. those in which the protocol shows "ALL"
and the port numbers are zero, can be removed by the form:
"NAT DROP <localaddr>" e.g. "NAT DROP 192.168.0.2".
If the translation table entry includes port numbers, the
form:
"NAT DROP <local_address>[:port]" is required, e.g.
"NAT DROP 192.168.0.2:23".
If the translation entry is protocol-specific, the protocol
must be specified when removing the entry, e.g.:
"NAT DROP 192.168.0.2 TCP".
NAT LIST
This command currently requires no arguments.
Order of Entries in NAT table
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The order of entries within the translation table is
important, because XRouter will translate upon the first
matching entry. This gives you maximum flexibility to cater
for your particular needs. As a general rule, port-specific
and protocol-specific entries should be declared before
non-specific "catch-all" entries. Overload entries can be
declared anywhere, providing they don't inadvertently "hide"
a static translation for the same address.
Consider this example:
NAT ADD STATIC 192.168.0.2:87 44.131.91.2:23 TCP
NAT ADD STATIC 192.168.0.2 44.131.91.2
NAT ADD OVERLOAD 192.168.0.0 44.131.91.3 255.255.255.240
In the above example, TCP frames originating from port 87 on
local host 192.168.0.2 will be translated by the first entry,
to look like they originated from port 23 on global host
44.131.91.2.
UDP and all other TCP frames from that host will be translated
by the second entry, which leaves the port numbers alone.
This entry also translates "portless" protocols such as AXIP,
ICMP, IPIP etc.
The third entry translates any TCP or UDP frame originating
from local hosts 192.168.0.0 to 192.168.0.15, excluding
192.168.0.2, to look as if it originated at 44.131.91.3.
If the second entry had been placed before the first, it would
never have been executed, because the non-specific static
entry would have intercepted *every" frame from 192.168.0.2.
If the overload entry had been placed first, it would have
intercepted every TCP and UDP frame from local hosts 0 to 15,
so the port specific static would never have been executed.
Routing Table Requirements
~~~~~~~~~~~~~~~~~~~~~~~~~~
In addition to the translation table entries, you must ensure
that IP routing to the target system is correctly configured.
Network Address Translation is applied *before* the packet is
routed. This means that for "outbound" packets, i.e. those
originating on the "private" subnet, routing to the "public"
net should be defined. For "inbound" packets, i.e. those
originating on the public net, addressed to one of the global
NAT addresses, the should be a routing entry which will route
the translated address to the *private* subnet. This is best
illustrated with an example:
In IPROUTE.SYS....
ROUTE ADD 44.0.0.0/8 44.131.90.6 11 d
ROUTE ADD 192.168.0.1/32 * 14 d
NAT ADD STATIC 192.168.0.1 44.131.91.3
The first entry routes all outbound 44-net packets to peer
44.131.90.6 on port 11.
The second entry routes packets addressed to 192.168.0.1 onto
port 14 which is the Ethernet LAN.
The third entry translates destination address 44.131.91.3 on
incoming packets into 192.168.0.1 before sending the packet on
the LAN as dictated by the second entry.
Internet Connection Sharing
~~~~~~~~~~~~~~~~~~~~~~~~~~~
If one of XRouter's ports is connected to the Internet (e.g.
by dialup or cable modem), you may use dynamic PAT to allow
other computers on a LAN to share the connection. Assuming
the computers on your LAN use addresses in the range
192.168.0.1 to 192.168.0.255 (this is the range normally used
by Windows), the NAT entry should look like this:
NAT ADD OVERLOAD 192.168.0.0 0.0.0.0 255.255.255.0
Note the special 0.0.0.0 entry, which tells XRouter to
translate the source address on outgoing frames to the address
of the port on which they are sent. This is required if your
Internet connection uses a dynamic IP address, but if your
address is static you may insert it in place of the 0.0.0.0.
If you don't have a DNS server on your LAN, you will need to
set up the LAN computers to use Xrouter as their DNS. You
will also need to tell XRouter the address of at least one
external DNS, either by including a "DNS=<ipaddr>" statement
in XROUTER.CFG, or by using a "DNS ADD <ipaddr>" command.
XRouter will then act as proxy DNS for the computers on the
LAN.
Summary
~~~~~~~
a) Use NAT ADD... in IPROUTE.SYS to define translations.
b) Add IP routing for the *global* NAT addresses.
c) Use NAT... commands to display / adjust NAT on the fly.
d) Report problems to me.
References:
~~~~~~~~~~~
RFC791 - Internet Protocol
RFC792 - Internet Control Message protocol
RFC793 - Transmission Control Protocol
RFC1631 - The IP Network Address Translator
RFC1700 - Assigned Numbers
RFC1918 - Address Allocation for Private Intranets
SEE ALSO
NAT(1) -- NAT Commands
IPROUTE.SYS(8) -- IP Routing / Configuration File
NCMP
NCMP(9) XROUTER REFERENCE MANUAL 25/10/2023
NAME
NCMP -- NetRom Control Message Protocol.
SYNOPSIS
NCMP has been implemented in XRouter since July 2001. It is
an extension to the NET/ROM protocol, facilitating extra
tools for network administration, such as network probing
and unknown route reporting. It was described in Packet
White Paper PWP106, most of which is reproduced below.
INTRODUCTION
The Netrom Control Message Protocol is part of ISO Layer 3,
and sits just above the routing sub-layer. It is intended to
be transparently routable by any NET/ROM node, whether or not
that node implements the protocol.
To that end it uses NET/ROM "protocol extension" packets,
which should (in theory) be routed "as-is" by any node which
doesn't understand them.
PACKET STRUCTURE
NCMP datagrams consist of a normal Layer 3 NET/ROM header,
followed by the NCMP header, which may in some cases be
followed an optional NCMP payload.
The NCMP header is of variable length, and its first 5 bytes
occupy the space normally used by a NET/ROM layer 4 header,
as depicted in the diagram below:
|<------------- NCMP Header ----------->|
-----------------------------------------------------------
| L3hdr | Fam | Prot | Type | Code | 00 | (opt) | (Payload) |
-----------------------------------------------------------
Field Bytes Description
--------------------------------------------------------
L3hdr 15 NET/ROM Layer 3 Header
Fam 1 Protocol Family = NET/ROM = 0x0f
Prot 1 Protocol = NCMP = 0x00
Type 1 Type of NCMP packet (see below)
Code 1 Usage depends on "type".
Opt var Additional fields present in some types only
Payload var Optional payload present in some types only
The upper 4 bits of the TYPE are reserved for future
expansion, and are set to zero in this version. The lower 4
bits encode the packet type as follows:
Type Purpose
-----------------------------------
0 Probe Request
1 Probe Reply
2 Echo Request
3 Echo Reply
4 Routing Information Unicast
5 Destination Unreachable
PACKET TYPES
The following diagrams omit the L3 header for clarity:
Type 0: Probe Request
-------------------------------------------------
| 0F | 00 | Type=0 | TTL | 00 | Tick(h) | Tick(l) |
-------------------------------------------------
"TTL" is a Time To Live, limiting the no. of hops the
probe may propagate. This value is also copied into the
L3 TTL field.
"Tick" is a 16 bit tick counter, sent high octet first.
This is returned unmodified by the responder, and used
to calculate the Round Trip Time (RTT).
A node which responds to a probe request must return the
whole datagram (including any additional fields not
specified above), after changing the NCMP type from 0 to
1 and inserting the TTL from the L3 header into the NCMP
TTL field.
Type 1: Probe Reply
-------------------------------------------------
| 0F | 00 | Type=1 | TTL | 00 | Tick(h) | Tick(l) |
-------------------------------------------------
"TTL" is the TTL from the L3 header of the rcvd probe.
"Tick" is the 16 bit tick count from the probe datagram
Type 2: Echo Request
------------------------------------------------------
| 0F | 00 | Type=2 | TTL | 00 | ID | Seq | Opt payload |
-------------------------------------------------------
"TTL" is the initial Layer 3 TTL
"ID" is a unique 16 bit identifier, sent high octet
first, allowing the originator to match responses with
the requests.
"Seq" is a 16 bit sequence number, sent high octet first.
Usually carries a timestamp, allowing the RTT to be
computed.
Type 3: Echo Reply
-------------------------------------------------------
| 0F | 00 | Type=3 | TTL | 00 | ID | Seq | Opt payload |
-------------------------------------------------------
"TTL" is the TTL from the L3 header of the received
request.
The ID, SEQ and Payload fields must be returned
unmodified.
Type 4: Routing Information Unicast
-----------------------------------------------
| 0F | 00 | Type=4 | xx | 00 | INP3 Data |
-----------------------------------------------
"xx" = unused field
Type 5: Destination Unreachable
-----------------------------------------------
| 0F | 00 | Type=5 | Code | 00 | Returned Data |
-----------------------------------------------
"Returned Data" is the first 28 octets of the unrouted
datagram.
"Code" is as follows:
Code Meaning Explanation
---------------------------------------------------------
0 Host Unknown The router does not know the
destination node.
1 Host Unreachable The destination node is known, but
there are no viable routes at this
time, due to obsolescence or link
failure.
2 Net Unreachable The number of hops to the target
system is more than the remaining
Time To Live.
3 Proto Unreachable The destination node does not know
how to handle the requested
protocol.
4 Service Unreach The requested service is not
implemented at the destination
node.
5 TTL Exceeded The datagram could not be routed
any further because its Layer 3
Time to Live reached zero.
6 Frag Required The datagram is too large for the
outgoing link, and the link does
not support fragmentation.
7 Source Quench The datagram could not be handled
at this time due to insufficient
resources. This situation is
temporary. Upon receipt of this
message, the sender should reduce
the sending rate.
PROBES
Probe datagrams are intended for "peer discovery". In this
context, PEER means another NCMP-capable node. At this time,
only XRouters are NCMP-capable, but wider adoption would be
desirable.
Probes are currently dispatched with an initial TTL of 6, to
nodes with a quality of 20 or more and a one way trip time
below 1 minute. These figures are likely to be revised down
in future. If no reply is received, the probe interval
increases.
Upon receipt of a probe, no matter whom it is addresed to,
an NCMP peer returns it to the sender. Thus only the nearest
peers are discovered.
INFORMATION EXCHANGE
The purpose of peer discovery is to facilitate the transfer
of additional network-related information across a legacy
network, most of which which doesn't, and probably never
will, embrace INP3.
Such information may include a node's position, town,
software type and version, contact details, Amprnet IP
address, available services and so on. These things make
Packet Radio more interesting.
Once a peer had been identified, XRouters are able to
exchange INP3 data "tunneled" inside NCMP type 4 datagrams,
even if the intervening nodes are not INP3-capable.
A consequence of this exchange is to allow expansion of, and
experimentation with, INP3-like options, without breaking the
existing INP3 protocol. When proven, such extensions could
be incorporated into the "official" INP3 standard if there
was agreement.
ECHO REQUESTS
Echo requests are intended for testing the network, and are
invoked using XRouter's NPING (Netrom Ping) and NTRACERT
(Netrom Traceroute) commands.
SUPERVISORY
"Destination unreachable" messages are intended to improve
the user experience, by quickly reporting network problems,
instead of leaving the user waiting for a reply that will
never come.
For instance, if the user tries to connect to a node that is
in the nodes table but no longer has a viable end-to-end
path, one of the intervening nodes should quickly return a
"destination unreachable" message, and the user would be
informed. Without this, the user could typically wait six
minutes (L4T1 * L4RETRIES) for a "Connect failed" response.
With the exception of echo and probe, NCMP datagrams are
never sent in response to NCMP.
SEE ALSO
NPING(1) -- Send NetRom Echo Request(s).
NTRACERT(1) -- NetRom TraceRoute.
PEERS(1) -- Show Nearest NCMP-capable nodes.
INP3(9) -- Inter-Node Protocol 3.
NDISXPKT
NDISXPKT(9) XROUTER REFERENCE MANUAL 17/10/2023
NAME
NDISXPKT -- NDIS Driver for XRouter (XR32 only).
DESCRIPTION
NdisXpkt is an optional kernal-mode driver which allows XR32
to share an Ethernet NIC with Windows, and to have its own
completely independent IP address.
The driver was written for XR32 in 2006 by Anthony Martin
M1FDE, sadly now silent key.
Unfortunately, it can only be used with Windows 2000 and
Windows XP.
Do I Need NdisXpkt?
~~~~~~~~~~~~~~~~~~~
The NdisXpkt driver is only required if you wish to share an
Ethernet NIC with Windows. XR32 will work without it, but you
will not have the full range of XR32's functionality.
Without NdisXpkt XR32 is not able to:
- Have its own Ethernet LAN IP address
- Route "raw" IP via the Ethernet NIC.
- Trace any raw IP activity via Ethernet NIC.
- Use IPEncap encapsulation via Ethernet NIC.
If you don't need any of the above, you don't need NdisXpkt.
Explanation
~~~~~~~~~~~
Without the NdisXpkt driver, XR32 is forced to use facilities
provided by the Windows TCP/IP stack. Those facilities are
limited, and in some cases are deliberately crippled by
Microsoft. For example, later versions of Windows XP block
the use of IPENCAP (protocol number 4).
Since no-one likes having to install and load drivers, the
majority of sysops now tend to use XR32 without NdisXpkt.
However this is a **basic** mode, with limited facilities,
compared to the "full" (NdisXpkt) mode. It was only intended
as a stop-gap measure, until a 64-bit driver could be written.
In basic mode, XR32 can originate and terminate all the common
higher-level protocols (TCP, UDP, ICMP etc.), but cannot
handle datagrams via the *Ethernet* NIC at the raw IP layer
(IP via SLIP, PPP or IP-over-AX25 connections are not
restricted however). This means that XR32 cannot act as an
IP router for datagrams to or from the LAN, unless those
datagrams are encapsulated. And it cannot trace IP headers
to/from the LAN, although it is able to trace the "inner" IP
headers of encapsulated datagrams.
If you are using Win2000 or WinXp, and wish to install
NdisXpkt, please read on...
Installing NdisXpkt
~~~~~~~~~~~~~~~~~~~
Before you can use NdisXpkt, it must be installed and started.
NdisXpkt comes in two flavours, one for Windows 2000 and one
for Windows XP. Install only the one to match your operating
system. The distribution package contains both, in separate
directories named "Windows 2000" and "Windows XP".
There are detailed installation instructions with screenshots
in the INSTALL.HTM document of the NdisXpkt package. They are
summarised here:
a) To install drivers, you need to log in using an account
with Administrator priviledges.
b) Extract the files from the .zip archive into a temporary
directory on your hard drive. You can remove this
directory when you've finished installing. Remember where
you put them - you'll need them later.
c) Open the control panel and double-click "Network
Connections".
d) You may only have one or two network connections in the
lower part of the pane. Select one of the network
connections. It doesn't matter which you choose, a new
driver will bind itself with all of them. If you don't
have any networks in the lower pane, you need to install
one. Either a network card, a USB network adapter, or a
wireless LAN. This driver can't be used without one.
e) Hold the right mouse button and select "Properties" in the
menu that appears.
f) This window shows the different protocols that are bound
to this network device. We want to install something, so
click the button marked "Install..."
g) On the dialog that appears, select "Protocol" and click
"Add".
h) You don't want any of the standard choices, so click
"Have Disk". The "Install From Disk" dialog should appear.
i) Click "Browse" and navigate to the folder where you
unzipped the files. It will only show you .inf files.
When you've found "ndispkt.inf", select it and click
"Open", then "OK".
j) Digital signing is not required for NDIS drivers, so click
OK to install.
k) The LAN connection properties box should now show
"NdisXpkt" in the list.
l) Click "Close" and you're done.
Uninstalling NdisXpkt
~~~~~~~~~~~~~~~~~~~~~
a) Make sure XR32 is not running, otherwise the system may
not allow the driver to be stopped and uninstalled.
b) Proceed as above until you reach the network connections
properties box.
c) Select the NdisXpkt protocol in the scrollable list.
d) Click "Uninstall". Windows reminds you that uninstalling
removes it from all network ports.
e) Click "Yes". At this point the protocol should disappear
from the list.
f) Click "Close".
Starting NdisXpkt
~~~~~~~~~~~~~~~~~
To start the driver manually, open a command window and type:
net start NdisXpkt
At which point you should see the response:
"The NdisXpkt service was started successfully".
Note that the driver name is case sensitive and must be typed
EXACTLY as above. If you type it any other way, the driver
will start but will not be available to XR32.
NdisXpkt only needs to be started once per session. You only
need to start it again if you restart the operating system.
It is hoped to automate the startup in future versions of
XR32.
In the meantime, you should be able to start NdisXpkt and
XR32 using a batch file containing the following instructions:
CD \MyProgs\XR32 <-- or wherever your XR32 is
net start NdisXpkt
XR32
The batch file can be created using Notepad and saved as
"STARTXR32.BAT" or something like that. Test it to make sure
it works. It may need a short delay between "net start" and
"XR32" to allow time for the NdisXpkt service to start. A 4
second delay can be achieved by insterting "Ping localhost"
When you are sure that the batch file is working, drag it
(or a shortcut to it) into Start Menu\Programs\Startup, and
it should execute when Windows boots.
Configuring an NdisXpkt INTERFACE
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
XR32 interfaces to NdisXpkt driver via an EXTERNAL interface,
which is declared in XR32.CFG as follows:
INTERFACE=1
TYPE=EXTERNAL ; External device driver
ID=Ethernet LAN
PROTOCOL=ETHER
MTU=1064
ETHADDR=00:07:95:fa:d9:3b
ENDINTERFACE
Note that the ETHADDR is mandatory and must match the MAC
address used by the chosen NIC. To find your NIC's MAC
address, open a command window and type
IPCONFIG /ALL
then look for "Physical address", e.g.
Ethernet adapter Local Area Connection:
Physical Address. . . : 00-07-95-FA-D9-3B
Alternatively, type "ROUTE PRINT" and look for the name of
the NIC in the list, e.g.
Interface List
0x1 ....................... MS TCP Loopback interface
0x2 ...00 07 95 fa d9 3b .. SiS 900 PCI Fast Ethernet
As you can see, there are several different ways of depicting
a MAC / physical / Ethernet address. XR32 requires the use of
colons ':' between the 6 pairs of characters.
Configuring a PORT
~~~~~~~~~~~~~~~~~~
The Ethernet port is declared like this:
PORT=1
ID=Ethernet
INTERFACENUM=1
IPADDRESS=192.168.0.2
NETMASK=255.255.255.0
etc...
Make sure you choose a different IP address to the one
Windows is using!
Note: The use of interface type EXTERNAL for NdisXpkt is a
temporary measure, liable to change in future.
SEE ALSO
IP-STACKS(6) -- TCP/IP Stacks in XR32
MPORT(1) -- Set port to monitor
NFTP-SRV
NFTP-SRV(9) XROUTER REFERENCE MANUAL 7/9/2023
NAME
NFTP-SRV -- Netrom File Transfer Protocol Server
DESCRIPTION
NFTP (Netrom File Transfer Protocol) is basically a form of
FTP over NetRom. It uses fairly standard FTP server commands,
but unlike FTP, in its simplest form it shares a single
stream for both commands and data.
NFTP uses NetRomX service 21, the same number as regular FTP.
Strictly speaking, NFTP is a misnomer, because the protocol
can be used over any reliable byte-ordered stream, be that
AX25, NetRom or TCP.
Although NFTP can be used by anyone, it is primarily intended
for sysops to exchange files with each other. The protocol
permits limited access to "public" files without login.
The server can be accessed in one of 3 ways:
If the source node is NetromX-capable, the user can connect
directly to service 21 on the target node. For example,
"C G8PZT 21". A typical response is shown:
c g8pzt 21
DOTXR:VK2DOT-1} Trying G8PZT::21...
DOTXR:VK2DOT-1} Connected to G8PZT::21
220 G8PZT NFTP ready - Restrictions apply
Alternatively, the SYSOP of the source node may use the
"NFTP <target>" command to invoke an NFTP client which
connects to the target node. This client is not available to
non-sysops, but there's no restriction on standalone clients.
If the source node is *not* NetromX-capable, the user must
connect to the target node then issue the NFTP command,
supplying the target node's callsign as an argument.
For example, if the user was connected to VK2DOT and wanted
to connect to G8PZT's server, he would issue "C G8PZT",
wait for connection, then issue "NFTP G8PZT":
c g8pzt
DOTXR:VK2DOT-1} Connected to G8PZT
nftp g8pzt
G8PZT:KIDDER} Trying server
220 G8PZT NFTP ready - Restrictions apply
Once connected to the server, the HELP command reveals the
available commands and their syntax:
help
211-Cmds: ABOR CWD HELP LIST MDTM NLST NOOP
211-Cmds: PASS PWD QUIT REST RETR STOR TYPE USER
211-(Additional commands available after login)
211-
211 Use HELP <cmd> for syntax etc.
help stor
211-STOR Upload file to server
211 Syntax: STOR <size> <filename>
Login (using USER and PASS commands) is optional, and
intended only for sysops.
Unlogged users are restricted to a "public" directory, which
by default is located at FTP/public. The true location is not
shown to users. They cannot climb out of this directory, nor
create any directories within it. It is purely a space for
sysops and unlogged users to place publicly accessible files,
such as useful documents, software etc. For example:
list
150 OK 286
04-19-2021 02:41AM <DIR> .
06-20-2020 04:07AM <DIR> ..
04-19-2021 02:41AM 49375 repeaterlist.csv
04-19-2021 02:36AM 93162 rfc8200.txt
4 file(s) 150,729 bytes
2 dir(s) 398,048 bytes free
226 File sent ok
The main protocol differences between FTP and NFTP are in the
commands and responses associated with the transfer of data,
i.e. commands like LIST, STOR and RETR.
When a file or directory listing is requested using LIST or
RETR, the server replies with the line "150 OK n", where n is
the exact filesize in bytes.
After receiving this line, the client must treat the next
"n" received bytes as data, to be saved or displayed. After
sending the data, the server sends the line
"226 File sent ok", and is ready for the next command.
The syntax to upload a file is "STOR <bytes> <filename>",
for example, "STOR 96507 xrpi-manual.txt". If this is
acceptable to the server, it responds "150 OK <bytes>".
Upon receiving this line, the client must send exactly
<bytes> bytes of data. The server will not return to command
mode until it has received at least the specified number of
bytes. Any excess bytes sent by the client are discarded by
the server.
Thus you can read text files directly to your monitor, and
create them directly from your keyboard if required.
NOTE
Service 20 is reserved for possible future use as a separate
"data" channel.
SEE ALSO
NFTP(1) -- Start Netrom File Transfer Protocol Session.
NFTP-SVC(9) -- NetRomX NFTP Service.
SERVICES(9) -- NetRomX Standard Services.
NFTP-SVC
NFTP-SVC(9) XROUTER REFERENCE MANUAL 22/9/2023
NAME
NFTP-SVC -- NetRomX File Transfer Service.
DESCRIPTION
NetRomX service 21 connects to XRouter's NFTP server. This
server allows files to be transferred across the NetRom
network instead of TCP/IP. It uses similar commands to FTP,
but shares a single stream for commands and data.
The NFTP server is also available from XRouter's command
prompt.
For more information, see NFTP(9).
SEE ALSO
NFTP(1) -- Start Netrom File Transfer Protocol Session.
NFTP-SRV(9) -- About the NFTP Server.
SERVICES(9) -- NetRomX Standard Services.
NFTP-SVC(9) END OF DOCUMENT
NTTY-SVC
NTTY-SVC(9) XROUTER REFERENCE MANUAL 7/9/2023
NAME
NTTY-SVC -- NetRomX TTYLink Service
DESCRIPTION
NetromX Service 87 is Netrom access to TTYLink - keyboard to
keyboard chat with the sysop. It is equivalent to telnetting
to TCP service 87, or using the YELL command on the target
node.
When a client connects to the server, the sysop of the server
is paged, and has 90 seconds to respond. The page consists of
a pop-up dialog on top of the sysop's current window, and an
audible sound. Note the latter only works on older-style PC's
which have a "PC Speaker", or have AUDIODEVICE defined.
At any point during or after the 90 seconds, the client has
the option to leave a short one-line message (160 chars max)
or to abort the call.
If the sysop takes more than 90 seconds to respond, and the
client has not disconnected, the sysop can still use the
"talk" command to initiate a chat with the caller.
Here's an example session where the sysop responds:
c mobile 87 s
VK2DOT-1:DOTXR} Trying G8PZT-1
VK2DOT-1:DOTXR} Connected to G8PZT-1
TTYLINK at MOBILE:G8PZT-1
Calling sysop for 90 seconds..
Type 'M' at any time to leave a short message,
or 'Q' to quit...
*** G8PZT-1 has come online to talk ***
Hello, why are you calling me?
Because I want to, silly!
Fair enough, it's mad talking to oneself you know...
I know, but no-one else is around.
Ok, bye for now
*** The other end terminated the chat
VK2DOT-1:DOTXR} Welcome back
And here's a session where the sysop didn't respond.
Although not strictly TTYlink, it is a useful compromise,
rather than allow an important call to be missed:
c mobile 87 s
VK2DOT-1:DOTXR} Trying G8PZT-1
VK2DOT-1:DOTXR} Connected to G8PZT-1
TTYLINK at MOBILE:G8PZT-1
Calling sysop for 90 seconds..
Type 'M' at any time to leave a short message,
or 'Q' to quit...
No response, please type a short (1 line) message now...
(or enter a blank line to skip this step)
Can you call me back to discuss xrpi release asap?
Message saved for sysop
Goodbye
VK2DOT-1:DOTXR} Welcome back
The message is stored in the sysop's PMS, and a flashing
asterisk on the top left corner of the status bar alerts the
sysop to its presence. The sysop can then access their PMS
to read the message like this:
CMD(B/H/K/L/R/S/?)>
l
Msg# Stat Rcvd Time To From Subject
6 PR 22/05 03:25 SYSOP G8PZT TTYLink msg from
G8PZT@VK2DOT-1
CMD(B/H/K/L/R/S/?)>
r 6
Msg#: 6
Rcvd: 22/05 03:25
From: G8PZT
To: SYSOP
Subj: TTYLink msg from G8PZT@VK2DOT-1
Can you call me back to discuss XRPi release asap?
CMD(B/H/K/L/R/S/?)>
It's all a bit untidy at present, but will hopefully be
tidied up in future revisons.
SEE ALSO
TALK(1) -- Talk to a user or another sysop.
TTYLINK(1) -- Keyboard chat with another TCP/IP system.
YELL(1) -- Page the sysop.
AUDIO(9) -- Audio Output.
SERVICES(9) -- NetRomX Standard Services.
PERMLINKS
PERMLINKS(9) XROUTER REFERENCE MANUAL 18/10/2023
NAME
PERMLINKS -- Permanent NetRom Neighbour Links.
SYNOPSIS
This file explains why XRouter tries to keep neighbour node
links permanently open, why that is desirable, and why you
shouldn't worry about it.
DESCRIPTION
Old-fashioned nodes close their AX25 level 2 links with
neighbour nodes after a period of inactivity, which can be
less than ideal...
Firstly, it takes a finite time to establish an AX25 L2
interlink from "cold", which adds an unnecessary extra
delay for NetRom link setup, and for L3 frames which arrive
infrequently. If it takes 5 seconds to establish a link,
and a frame has to pass through 10 nodes, that's an extra
50 seconds of delay!
Secondly there is the very common and highly disruptive
problem known as the "ONE WAY LINK". These can occur when
an RF path fades, or when there is local interference, or
when a transmitter, receiver, antenna, TNC or AX*P link
malfunctions, leaving one node hearing the other but not
vice versa.
When a one-way link occurs, one peer can hear the other's
nodes broadcasts, but there is no reverse path. The node
which received the broadcast mistakenly thinks it has a
route to the node which made the broadcast, but since the
two-way path required by an AX25 connection is not
available, no connection can be made. No traffic can be
transferred, so the neigbour node and all nodes advertised
by him are unreachable.
To make matters worse, the node which received the
broadcast advertises all the nodes learned via that
broadcast to its other neighbours. So in turn they think
they have routes to distant nodes, when in fact they don't.
The network is seriously disrupted by one broken link,
causing a black hole where all packets are LOST. This
situation can not recover until the one way link is fixed.
The Better Way
~~~~~~~~~~~~~~
In contrast, XRouter attempts to maintain permanent L2 links
between neighbour nodes. You may find this disconcerting,
but it has the following advantages:
Firstly, it removes the link establishment time, so NetRom
traffic can be routed without delay, no matter how
infrequently it arrives.
Secondly, it solves the "one way link" problem by promptly
detecting when the link cannot accept traffic, and marking
all nodes advertised by the peer as unusable, so that
alternative routes can be used.
Lastly, it enables continuous measurement of route quality
and round trip time, used in making routing decisions. RF
links, especially long ones, can be remarkably variable
throughout the day and night, and these problems can be
discovered through the process of continuous link audit.
There is no need for concern. The only cost associated with
keeping a link open is a tiny link check packet every 3
minutes. Hardly a great waste of bandwidth! Remember that
the old-fashioned way has a bandwidth cost too - at least
two packets to open a link and two to close it, in addition
to the link check packets. The benefits of permanent links
far outweigh the disadvantages.
How it Works
~~~~~~~~~~~~
If port QUALITY and NODESINTERVAL are both non-zero, as soon
as XRouter hears a nodes broadcast from a previously unknown
neighbour, it will attempt to connect to it. If the connect
is successful, the round trip time is measured, and the
route is considered viable. The link is checked every 3
minutes (adjustable via T3), and will close if non-viable.
If the connect fails, the route is marked as unusable,
therefore no nodes will be routed via it. The connection is
retried at regular intervals.
If the path is marginal, connection attempts may sometimes
succeed and sometimes fail. It is not worth using a route
like this, so you can prevent it from re-trying by locking
in the neighbour with a zero quality.
The ROUTES commands will show a ">" in the left-most column
if the interlink is fully open, a "~" if it is opening or
closing, or an "x" if the link can't be opened or has failed.
This provides a handy way of detecting link problems which
might otherwise go un-noticed.
SEE ALSO
ROUTES(1) -- NetRom Routes Commands.
NODESINT(7) -- Nodes Broadcast Interval.
QUALITY(7) -- Default NetRom Quality.
XROUTER.CFG(8) -- Main Configuration File.
PIPES
PIPES(9) XROUTER REFERENCE MANUAL 18/10/2023
NAME
PIPES -- Frame Pipes.
DESCRIPTION
Frame pipes allow frames received (and optionally sent) on
one port to be copied to another port.
A typical use might be to allow a PMS on one port to see
the traffic on another port, e.g. UNPROTO headers from a
local BBS.
Note that this is *not* the same as digipeating. With
digipeating, the user must specify a digipeater in the path,
but with frame piping the packets are tunneled from one port
to another with no intervention from the user.
The facility is enabled by including the PIPE keyword within
a port definition, e.g. PIPE=4 would pipe frames to port 4.
If PIPE=0, or the keyword is omitted altogether, no piping
takes place.
SELECTIVE PIPES
By default, pipes are not selective, i.e. they pass traffic
from any source callsign to any destination callsign (with
the exception of Budlisted callsigns of course). On a busy
channel, this could result in a lot of unnecessary traffic
being piped.
Pipes can be made selective however, by adding a comma
delimited callsign list, e.g. "PIPE=4 GB7PZT,KDRBBS". This
reduces the loading on the destination port, by piping only
those frames with the specified callsigns in the destination
field.
Pipes can also be made selective in terms of the types of
traffic they pipe (AX25, NetRom etc). This is controlled
by PIPEFLAG (see OPTIONS below)
BIDIRECTIONAL PIPES
A pipe normally only allows traffic in one direction, so in
order to have two way traffic you must either set up a
reverse pipe on the partner port, for example:
(on port 3) PIPE=4 ; Pipe frames to port 4
(on port 4) PIPE=3 ; Pipe frames to port 3
Or you may configure the pipe to be bi-directional, by
setting the appropriate value in PIPEFLAG (see below)
If a frame is piped on a bi-directional pipe, the source
callsign is remembered so that responses will be piped back
to the sender. XRouter remembers the last 20 callsigns that
used a pipe.
Bidirectional pipes are useful in cases where a BBS has a
front end router. Simply set up bi-directional selective
pipes from each user port to the BBS port. The BBS will
then allow direct connection and will respond to resync
requests.
Bi-directional pipes are actually only quasi-bi-directional,
because they can only send *responses* in the reverse
direction. In the above BBS example, outgoing connections
cannot be initiated to callsigns which haven't already used
the pipe.
For most purposes this isn't a problem, because it is the
users that tend to initiate the connections, not the BBS.
However, there may be cases where the BBS needs to poll the
user's PMS, or to initiate forwarding to another BBS. If the
callsign is remembered from a previous session, this will
work, otherwise it will fail.
The only way to have truly unconditional two-way piping is
to set up forward and reverse pipes as detailed above.
OPTIONS
The types of frame to be piped can be controlled using the
optional PIPEFLAG keyword, which is ignored unless piping
is active.
The value for PIPEFLAG is made up by adding together the
desired options represented by the following numbers:
1 - UI frames *not* addressed to nodecall/alias.
2 - Non-UI frames *not* addressed to nodecall/alias.
4 - UI frames addressed to nodecall/alias.
8 - Non-UI frames addressed to nodecall/alias.
16 - UI frames transmitted by the router.
32 - Non-UI frames transmitted by the router.
64 - Allow budlisted users to be piped.
128 - Netrom & nodes broadcast frames.
256 - IP / ARP frames.
512 - Bi-directional piping.
e.g. PIPEFLAG=5 will pipe all received UI frames, but not
those which originated from XRouter itself.
If PIPEFLAG is not specified, the default value is 3, which
pipes all regular AX25 Layer 2 traffic. You are *STRONGLY*
recommended to use the default value unless you specifically
need to see additional traffic.
LIMITATIONS
You may pipe several ports to a single destination port, but
you can only have one *outgoing* pipe from any port.
CAVEATS
Pipes are capable of generating an immense amount of traffic,
so use them with care - your target port MUST be capable of
dealing with the traffic load, and you should avoid setting
up a combination of pipes which might cause an endless loop!
FILES
The PIPE and PIPEFLAG directives are used in the PORT
sections of XROUTER.CFG.
SEE ALSO
PIPE(1) -- Display / Set Frame pipe.
PIPEFLAG(7) -- Frame Pipe Option Flags.
BCAST(9) -- Frame Broadcasting.
XROUTER.CFG(8) -- Main Configuration File
PMS
PMS(9) XROUTER REFERENCE MANUAL 10/1/2024
NAME
PMS -- Personal Message Server / Mailbox.
SYNOPSIS
This file describes XRouter's inbuilt mailbox which can be
used for both private messages and bulletins. The terms "PMS"
and "mailbox" are used interchangeably.
DESCRIPTION
XRouter's mailbox is a no-frills message storage and retrieval
system which was originally intended for exchanging messages
between users and the sysop, hence the legacy name PMS.
The mailbox understands SIDs (System IDentifiers), MIDs
(Message IDentifiers) and BIDs (Bulletin IDentifiers),
hierarchical addressing, bulletins, MBL forwarding and reverse
forwarding, so it can also be used to exchange private mail
and bulletins with a full-service Bulletin Board System
(BBS). In fact it is a mini-BBS in its own right, as users
may leave bulletins for others to read.
There is no limit to the number of messages or the size of a
message. If a disk is available, messages are stored on the
disk and will persist until killed, or expired by age. If no
disk is available, messages are stored in RAM and will be lost
if XRouter is restarted.
If there is unread private mail addressed to the sysop, the
latter is alerted by "PMS" flashing to the left of the node
callsign on the top status bar.
BASIC CONFIGURATION
The mailbox can be configured in one of several "modes"
controlled by the PMSTYPE directive in XROUTER.CFG. The
default is mode 1 i.e. standard PMS. To configure the mailbox
as a full BBS instead, use PMSTYPE=4. See the section 7 page
for PMSTYPE.
The mailbox is always available from the node's command line,
but if you want to enable "direct" AX25 connections, you must
configure at least PMSCALL in XROUTER.CFG.
If you want your mailbox to be visible on the NetRom networ
as well, you must additionally add PMSALIAS and a non-zero
PMSQUAL. For example:
PMSCALL=G8PZT-2
PMSALIAS=PZTPMS
PMSQUAL=50
If you plan to exchange mail with other systems, you must set
the PMSHADDR directive in XROUTER.CFG. Also note that the
agreed specification for mail forwarding does not allow SSID's
in mailbox callsigns, so even if PMSCALL includes an SSID, the
mailbox "identity", as far as the mail forwading system is
concented, is PMSCALL without SSID.
Additional configuration options can be specified in PMS.CFG,
which is explained in its own section 8 MAN page.
CONNECTING TO THE MAILBOX
Whatever the setting of PMSTYPE, the mailbox can always be
accessed using the "PMS" command or by a connection to
NetRomX service 2.
If PMSTYPE=4, the mailbox is accessed via the "BBS" command
instead. If the "PMS" command is used in this mode, only
personal mail is shown by default.
In addition, if PMSCALL is defined in XROUTER.SYS, users may
perform an AX25 level 2 connect directly to the PMSCALL.
(PMSCALL must not not be the same as NODECALL)
If PMSALIAS and a suitable PMSQUAL are also defined, users may
also connect directly to the mailbox from another node, using
"legacy" NetRom.
At the time of writing there is no direct TCP/IP access to the
the PMS, because a regular Telnet connection followed by the
issuing of the "PMS" command is sufficient.
COMMANDS
The mailbox has its own rudimentary command set, separate from
the node commands. The following is a possibly incomplete list.
(A full list can be obtained using the command "? **")
<n> [n1 n2..] Read message(s)
? [*] Syntax and brief help
A[bort] Aborts paused message reading/listing
B[ye] Disconnect from the PMS.
CB <cat> [dist] Copy any type of message to a bulletin
CP <to> [at] Copt any type of message to a private msg
EH <msgnum> Edit header fields for <msgnum> (*3)
EX[port] <n> <file> Export msg <n> to <file> (*3)
H[elp] Display list of commands.
HO[ld] <msg> Hold a message (*3)
FF Force Forwarding run (*3)
FP Force Polling run (*3)
H[elp] [topic] Display help for PMS command or topic
I[nfo] <call> Display all WP info for <call>
I@ <bbs> List users with <bbs> as their 'home' BBS
IC <call> List users with pallsign <call> (*1)
IH <haddr> List users at hierarchical address <haddr>
IM[port] <file> Import message(s) from MBL-format file (*3)
IN <name> List users called <name> (*1)
IQ <qth> List users at <qth> (*1)
IZ <zip> List users at <zip> / locator (*1)
J [max] Show most recent [max] callers (default 10)
K[ill] <n ...> Kill one or more messsages
K> <call> Kill messages TO <call> (*1)(*2)
K< <call> Kill messages FROM <call> (*1)(*2)
K@ <dist> Kill messages AT <distribution> (*3)
KF [call] Kill Forwarded msgs [TO call] (*1)(*3)
KH [call] Kill Held msgs [TO call] (*1)(*3)
KM Kill Mine (messages you have read)
KR [call] Kill Read messages [TO call] (*1)(*3)
L[ist] List messages and bulletins.
L[ist] <n> List messages starting at number <n>
L[ist] <f> <l> List messages from numbers <f> to <l>
L> <to> List messages TO callsign or category
L< <from> List messages FROM callsign
L@ <at> List messages AT a distribution
L$ [to] List messages waiting to be forwarded
LA <n> List oldest <n> messages (same as LO)
LB [n] List [max of n] Bulletins backwards
LC [cat] List bulletin categories (*1)
LF [to] List sucessfully Forwarded messages
LH List held messages (*3)
LL <n> List the Last (most recent) <n> messages
LM List Mine (all messages addressed to you)
LN List New (unread) mail addressed to you
LO <n> List oldest <n> messages (same as LA)
LP [n] List [max of n] Private messages
LR [to] List private mail that has been read
LS <text> List messages whose subject contains <text>
LT <text> List messages containing <text> in body
LU [to] List Unread messages
M[ine] List messages sent by you
MB <file> <cat> Make Bull from file to category <cat> (*3)
MF <n> <file> Make File from message <n> (*3)
MFH <n> <file> Make File from message, incl headers (*3)
MP <file> <to> Make Private message from a file (*3)
N[ext] Read next message in a "reading list"
N[ame] [name] Display or set your name in White Pages
NC [on | off] Display/set your ANSI colour preference
NH [bbs] Display or set your Home BBS
NI Summary of your user record
NP [lines] Set pagination [0=off]
NQ [qth] Display or set your QTH
NZ [zip] Display or set your Zip / Locator
Q[uit] Stop reading a list of messages
R> <to> Read messages TO callsign or category
R< <from> Read messages FROM callsign
R@ <at> Read messages AT a distribution
R[ead] <n ...> Read msg(s), hiding routing headers.
RH <n ...> Read message(s) showing routing headers
RM Read Mine (all messages addressed to you)
RN Read New (unread) mail addressed to you
S[end] Send a message to sysop.
SB <topic> Send bulletin to <topic>
SF Stop Forwarding run (*3)
SP <call> Send personal message to <call>
SR Send Reply to a message you just read
U[nread] <msg> Unread a message (mark it unread) (*2)
UH <n n | all> Un-hold one or more "held" messages (*3)
VF View Forwarding queue (*3)
(*1) Wildcards are allowed.
(*2) Non-sysops can only action their own messages.
(*3) Sysop-only
MESSAGE STATUS
Messages have a "status" indicator as follows:
Status ' ' indicates unread "local" private mail.
Status '$' indicates unforwarded non-local mail.
Status 'F' indicates forwarded non-local mail.
Status 'R' indicates local private mail that has been read.
Status 'H' indicates that the message is "held".
DISCONNECTING
To exit the mailbox, the user may send BYE or QUIT, or simply
disconnect.
Users who accessed the mailbox via the "PMS" or "BBS" commands
are returned to XRouter's "node" command prompt upon receipt
of BYE or QUIT. Users who accessed via any other method are
disconnected by these commands.
FILES
Messages are stored as individual files in the PMS
sub-directory of the XRouter working directory.
If PMSTYPE=4 (full BBS) the PMS directory may also contain
other files which control BBS operations, such as PMS.CFG,
BADWORD.SYS, DISTRIB.SYS, EXPORT.SYS, FWD.SYS, HOLD.SYS, and
REJECT.SYS. Their purpose is as follows:
BADWORD.SYS List of "bad" words which cause message hold.
DISTRIB.SYS Controls distribution of mail to other BBS's
EXPORT.SYS Controls exporting of messages to files
FWD.SYS Controls "forwarding" & "polling" operations
HOLD.SYS Controls message "holding"
PMS.CFG Additional configuration info
REJECT.SYS Controls rejection of unwanted mail.
Most of these plain text files contain their own
documentation.
HOUSEKEEPING
Optionally takes place at regular intervals (e.g. every 24
hours - specified on PMS.CFG), when the PMS is idle.
During this operation, out of date messages and message ID's
are purged, and (if configured to do so) the message base is
re-numbered to remove gaps and keep the message numbers
within a sensible range
MAIL IMPORT
At intervals less than a minute, the PMS will check the PMS
directory for the existence of a file called "mail.in". If the
file exists, the mail it contains is imported and the file is
deleted. Don't write directly to "mail.in" otherwise it might
be imported before you finish writing it. Create the file with
a different name, then rename it to "mail.in" when completed.
MAIL EXCHANGE
This is a two-part process, the parts being DISTRIBUTION and
FORWARDING. The former is controlled by DISTRIB.SYS, and the
latter by FWD.SYS.
Distribution is the process of queuing mail for onward
transmission to neighbouring mail handlers, and is an
instantaneous process, executed upon receipt of incoming mail.
Forwarding is the process of connecting to neighbouring mail
handlers, and sending the queued mail to them. It is a
background process, which can optionally be initiated when
mail is queued, or deferred until later.
NOTE
If a command alias, or an application, with the name "PMS" is
defined, it takes priority over the internal PMS.
AVAILABILITY
The PMS is available to all users. It is also available via
the HTTP interface. Some functionality is available via REST
and MQTT interfaces.
SEE ALSO
PMS(1) -- Start PMS Session.
PMSALIAS(7) -- PMS Alias
PMSCALL(7) -- PMS Callsign.
PMSHADDR(7) -- PMS Hierarchical Address.
PMSQUAL(7) -- PMS Quality.
PMSTYPE(7) -- PMS Mode.
PMS-SVC(9) -- NetRomX PMS Service
MQTT-PMS(9) -- MQTT Interface to PMS.
REST-PMS(9) -- REST Interface to PMS.
PMS-SVC
PMS-SVC(9) XROUTER REFERENCE MANUAL 22/9/2023
NAME
PMS-SVC -- NetRomX PMS Service.
DESCRIPTION
NetRomX service 2 is a direct connection to the sysop's
Personal Message/Mailbox System (PMS).
It is used by the "PMS <nodecall>" command, but is also
intended for human use.
Broadcasting PMS's as NetRom nodes might have been acceptable
long ago, but it clutters the nodes tables. The PMS service
allows sysops to disable the PMS nodes broadcast, or to
restrict the spread to the local area, while still retaining
connectivity from afar. All the user has to do is connect to
service 2 on the NODECALL.
SEE ALSO
PMS(1) -- Access Personal Message System(s)
PMS(9) -- Personal Message System
SERVICES(9) -- NetRomX Standard Services.
POP3SRV
POP3SRV(9) XROUTER REFERENCE MANUAL 17/12/2023
NAME
POP3SRV -- POP3 Server.
DESCRIPTION
The POP3 server allows sysops to collect their PMS mail using
a standard email client.
Account passwords are stored in POPUSERS.SYS in the form:
<account name> <password>
The server is enabled by specifying POP3PORT in XROUTER.CFG,
for example:
POP3PORT=110 110
You must declare a HOSTNAME, for example:
HOSTNAME=mobile.g8pzt.ampr.org
OPTIONS
SEE ALSO
POPUSERS.SYS(8) -- Account passwords for POP3 Server.
XROUTER.CFG(8) -- Main Configuration File.
PPP
PPP(9) XROUTER REFERENCE MANUAL 17/10/2023
NAME
PPP -- Point to Point Protocol.
DESCRIPTION
Point to Point Protocol (PPP) is a protocol suite intended for
use over simple links which transport packets between two
peers, such as an RS232 link (or pair of virtual COM ports).
Unlike SLIP, it includes facilities for link control (e.g.
management of a dial up link), user authentication,
negotiation of IP addresses, and the multiplexing of several
protocols across a common link.
PPP is designed to be self configuring. Most of the options
have standard default values, and peers negotiate anything
which differs from the default.
XRouter currently implements the most common PPP
sub-protocols:
- Link Control Protocol (LCP)
- Password Authentication Protocol (PAP)
- IP Control Protocol (IPCP)
Most sysops will have no need to remember these protocol names
and acronyms. However, for those who wish to experiment, each
protocol has its own set of commands.
PPP has largely replaced SLIP for dial-up Internet access, and
the interconnection of peers via RS232.
If you want to know more about the internal workings of PPP,
it is specified in RFC1661.
Configuring XRouter for PPP
~~~~~~~~~~~~~~~~~~~~~~~~~~~
There are three ways in which PPP may be used:
- RS232 (and virtual COM port) links.
- Dial-in.
- Dial-out.
The first case requires an INTERFACE to be configured to use
PPP, but the other two cases temporarily establish a PPP link
on a MODEM interface. Each case is described in more detail
below:
Using PPP on Wire / Virtual COM Links
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In XROUTER.CFG, define an interface with TYPE=ASYNC and
PROTOCOL=PPP. For example:
INTERFACE=1
TYPE=ASYNC
COM=1 ; 1-4 or specify INTNUM/IOADDR
SPEED=19200 ; Adjust as necessary
PROTOCOL=PPP
MTU=1600
ENDINTERFACE
Then "bind" a port to that interface thus:
PORT=1
ID=PPP link to Win98 ; Text to identify port
INTERFACENUM=1 ; Bind to PPP interface
IPADDRESS=192.168.0.4 ; Optional (see below)
ENDPORT
The use of IPADDRESS is optional. If the keyword is omitted,
XRouter's "global" IP address will be used on that port. If
the address is specified as 0.0.0.0, it signifies that a
"dynamic" IP address should be obtained from the peer,
otherwise the specified address will be used.
The port is now ready for PPP using the standard PPP defaults,
but if it requires any further configuration you may include
the relevant PPP configuration commands in the file
BOOTCMDS.SYS, which is read by XRouter at boot-up, after it
has finished reading XROUTER.CFG.
Using PPP on Dial-in links
~~~~~~~~~~~~~~~~~~~~~~~~~~
The INTERFACE and PORT should be configured for PROTOCOL=MODEM
as described in the manual section "PSTN Modem Support".
When a logged-in caller issues the command XLINK PPP, XRouter
automatically re-configures the port to support PPP. It then
looks for the file "PPPHOST.n", where n is the port number,
and if found, the PPP configuration commands within the file
are executed. The file may optionally contain NAT
configuration commands if required. The PPPHOST file is
optional. If not present, PPP will be initialised to the
standard defaults.
When the hardware link disconnects (e.g. user says goodbye or
hangs up, link times out, or sysop kills it), the port is
automatically re-configured back to its original MODEM
protocol.
Using PPP on Dial-out links
~~~~~~~~~~~~~~~~~~~~~~~~~~~
The INTERFACE and PORT should be configured for PROTOCOL=MODEM
as described in the manual section "PSTN Modem Support". The
local IP address follows the same rules as the wire-link case
above, but may be overridden temporarily by IPCP commands.
The dialler script (see DUN section) must contain the command
"MODE PPP" plus any required PPP configuration commands. Here
is an extract from a typical connection script:
; Link will use PPP
mode ppp
;
; Configure my authentication username and password
ppp pap user gb7pzt bsfjflavs
;
; Set inactivity timeout to 2 minutes
ppp idle 120
;
; Enable ppp state logging
ppp log 1
;
; Set my (static) IP address for the duration of this call
ppp ipcp local address 194.123.110.4
;
; Now dial the host
send ATDT07979654234
;
etc...
The PPP configuration will persist until the call terminates,
then the port will revert back to MODEM protocol to await the
next incoming or outgoing call.
PPP Configuration Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~
All PPP configuration commands start with "PPP", and are
described in the sysop command reference section. When used
from the command line, or with a BOOTCMDS.SYS file, the first
argument must be a port number. However, PPP commands used
within PPPHOST and dialler scripts *do not* include a port
number, because XRouter knows which port is executing the
script.
e.g. at the command line: PPP 3 IDLE 300
in a dialler script: PPP IDLE 300
IP Routing with PPP
~~~~~~~~~~~~~~~~~~~
When a PPP link opens, a route to the peer is automatically
added to XRouter's IP routing table. If the peer indicates
that it knows the addresses of a primary and secondary DNS,
those are added to XRouter's DNS list.
PPP Logging
~~~~~~~~~~~
PPP system activity can be recorded in file PPPLOG.TXT for
diagnostic purposes. The amount of detail is controlled by
the number specified in the "PPP <port> LOG n" command as
follows:
0 No logging
1 PPP start / stop / timeout events
2 As 1, plus layer up / down events
3 As 2, plus layer start / stop events
4 as 3, plus option accept / reject events
5 as 4, plus hexdump of configuration packets
You are advised against using the higher levels other than on
a temporary basis because they can create very large logfiles.
If logging is in use, you should regularly remove the logfiles
to prevent them growing too large.
SEE ALSO
BOOTCMDS.SYS(8) -- Bootup Configuration Commands File.
DIAL(1) -- Dial a PSTN connection.
DUN(1) -- Dial Up Networking Configuration Commands.
DUN(9) -- Dial-Up Networking.
PPP(1) -- PPP Configuration Commands.
PPPHOST.n(8) -- PPP Configuration File(s)
PSTN(9) -- PSTN Modem Support.
SCRIPT(9) -- Dialer Scripts.
XLINK(1) -- Establish a Temporary SLIP / PPP Interlink.
XROUTER.CFG(8) -- Main Configuration File.
PROXIES
PROXIES(9) XROUTER REFERENCE MANUAL 26/9/2023
NAME
PROXIES -- Proxy Connections.
DESCRIPTION
In this context, "proxies" are cross-protocol bridging
mechanisms which allow systems using one protocol to be
accessed using another protocol. They can also be used
to give "hidden" systems a network presence.
AX25 -> NETROM PROXY
====================
This facility allows AX25 level 2 callers to connect
"directly" to remote NetRom target callsigns, without
needing to connect first to XRouter then issue a downlink
connect request. In effect, it gives the NetRom target
system a local AX25 presence.
.------. .-------. .--------.
| user |-- Ax25 --| proxy |-- NetRom --| target |
'------' link '-------' link '--------'
(g5ur) (g8pzt) (gb7bbs)
.------. Ax25 link .-------.
| G5UR |-- G5UR -> <- GB7BBS --| G8PZT |
'------' '-------'
(Proxy at G8PZT masquerades as GB7BBS)
This facility is primarily for use in situations where
a BBS or PMS is wire-linked to a "front-end" router,
thus allowing the BBS callsign to be directly
connectible on any port for which the proxy call is
defined. You may find other uses....
A bi-directional selective frame pipe would provide a
similar effect, but only for systems directly connected
to XRouter, whereas PROXY allows the target system to be
located several hops away. Pipes can handle UI frames,
whereas PROXY is for connected-mode operations only.
Here's how it would be used on a typical set-up, which
has two machines (or a virtual COM port linking two
systems on the same machine). Only XRouter is connected to
the radios, the BBS being KISS-linked to XRouter's port 7.
----------- (1)
| Radio/TNC | ---.
----------- |
| .---------. .---------.
----------- (2)| | NODE | (7) KISS | GB7PZT |
| Radio/TNC |----|----| |------------| |
----------- | |(XRouter)| (rs232) | (BBS) |
| `---------' `---------'
----------- (3)|
| Radio/TNC |----|
----------- |
V
etc.
Without PROXY, level 2 users would have to connect to
XRouter, then issue the command "C GB7PZT",or "BBS" to
connect to the BBS.
With the line "PROXY=GB7PZT" in port 1's definition
(in XROUTER.CFG), users on port 1's frequency simply
connect to "GB7PZT" - XRouter intercepts the request and
answers on behalf of the BBS. It then connects via
NetRom to GB7PZT. In this case, the BBS is running on
top of BPQ, so it has a NetRom address.
If the target system (GB7PZT in this case) is not
reachable via NetRom level 4, the connect request is
refused.
If you wish to use this facility, you must add a
"PROXY=<call1>[,call2,...]" directive to each user PORT
concerned. Ports without the directive continue to
function as normal. You obviously wouldn't enable it
on your forwarding ports for example. You will notice
that you can have several callsigns on the line, each
separated by a comma, allowing you to act as a proxy
for more than one system.
Warning! DO NOT enable PROXY on any frequency which
is shared by the target system or you'll cause horrible
problems (both the target and the proxy will respond to
connects at the same time).
AX25 / NETROM -> TCP PROXY
==========================
This is an extension of the PROXY concept, allowing a
remote TCP/IP-only system to have NetRom and AX25
connectivity.
.------. .-------. .--------.
| user |-- Ax25 --| proxy |-- TCP/IP --| target |
'------' link '-.-----' link '--------'
|
.-------. |
| user2 |-- NetRom--'
| @node | link
'-------'
In the previous example, GB7PZT BBS used G8BPQ node
"underneath" the BBS to provide NetRom connectivity
across the KISS link. With the extended proxy, BPQ can
be removed altogether and the BBS can be run in pure
TCP/IP mode. This saves memory, whilst improving speed
and reliability. The BBS no longer has to support
multiple protocols or interface types, that job being
delegated to XRouter.
Instead of having to connect first to XRouter then issue
the awkward command "Telnet 44.131.91.2", users can
simply connect "directly" to the BBS callsign (GB7PZT)
on one of XRouter's radio ports. XRouter converts that
connection into a TCP/IP connection with the BBS, and
translates the data back and forth between AX25 and
TCP/IP.
Furthermore, the BBS callsign "GB7PZT" can be connected
to directly from XRouter's command line, and also included
in nodes broadcasts so it can be reached from a remote
node.
This type of proxy is created by putting an extended
PROXY statement in the GLOBAL section of XROUTER.CFG,
using the following format:
PROXY=<call> <alias> <qual> <ipaddr> <tcpport> [passwrd]
For example:
PROXY=GB7PZT KDRBBS 150 192.168.0.4 8888 bloggs
<call> is the NetRom and AX25 callsign for the
proxied system.
<alias> is the NetRom / AX25 alias for the proxied
system.
<qual> is the NetRom "quality" (0 - 255) controlling
visibility on the NetRom network.
<ipaddr> is the proxied system's IP address.
<tcpport> is the TCP service port number of the
proxied system.
<passwrd> is an optional password sent to proxied
system upon connection. This is used to
verify that the TCP connection originates
from an approved proxy.
AX25 and NetRom are pure binary channels, whereas standard
telnet is not. The proxied system must provide a pure
binary service port in order to make full use of this
facility for compressed forwarding etc. G8PZT's "XServ"
BBS software provides such a facility on TCP port 8888.
If you are a software author interested in adapting your
software to work with this proxy, the following information
will be useful:
Upon connection to the proxied system XRouter sends one line
of text ending in <CR><LF>, containing one or more
space-delimited fields. The first field is the callsign of
the connectee in the form "G8PZT-7" (ax25) or
"G6YAK-2@GB7BM" (NetRom). The second field is a password
which verifies the proxying system (note this is not the
user's password). Thereafter, the link switches to pure
binary, and in accordance with AX25 practice both systems
must send line ends as <CR> alone.
There is no limit to the number of proxies you may
configure.
NETROM -> AX25 PROXY
====================
This is similar to the NetRom -> TCP proxy described
above, but is intended to allow an AX25-only system to
have a NetRom presence.
.------. .-------. .--------.
| user |-- NetRom --| proxy |-- AX25 --| target |
|@node | link '-------' link '--------'
'------' ^
^-(Target callsign appears in)
(nodes tables on these nodes)
This is enabled by putting an extended PROXY statement
in the GLOBAL section of XROUTER.CFG, using the
following format:
PROXY=<call> <alias> <qual> <ax_call> <portnum>
For example:
PROXY=MB7UYL UYLBBS 150 G6KDR-3 7
<call> is the NetRom and AX25 callsign for the proxied
system.
<alias> is the NetRom / AX25 alias for the proxied
system.
<qual> is the NetRom "quality" (0 - 255) controlling
visibility on the NetRom network.
<ax_call> is the proxied system's AX25 L2 callsign.
<portnum> is the radio port the proxied system is
connected to.
The above example creates a NetRom node whose callsign
is "MB7UYL", alias "UYLBBS", with NetRom quality 150.
Anyone who makes a connection to either of these
addresses will instead be connected to the AX25 system
"G6KDR-3", attached to XRouter's port 7.
OPTIONS
Summary of the syntax for the 3 types of proxy....
AX25 -> NetRom:
~~~~~~~~~~~~~~~
PROXY=<call1>[,call2[,...]]
AX25 / NetRom -> TCP:
~~~~~~~~~~~~~~~~~~~~
PROXY=<call> <alias> <qual> <ipaddr> <tcp_port> [passwrd]
NetRom -> AX25:
~~~~~~~~~~~~~~
PROXY=<call> <alias> <qual> <ax_call> <portnum>
CAVEATS
Be *very* careful when mixing proxies and pipes, or you
will end up generating lots of FRMR's, and possibly
crashing the system. These are powerful tools and must
be used carefully.
Proxies are intended for use with your own systems only.
Do not act as a proxy for someone else's system without
their permission.
You must *NEVER* set up a proxy to give a NetRom
presence to a node which already has one!!
For proxies which include <portnum>, please ensure that
the port actually exists (sysops often rearrange ports
rendering the proxies inactive).
SEE ALSO
PROXY(7) -- Proxy Connectivity.
PIPES(9) -- Frame Pipes.
XROUTER.CFG(8) -- Main Configuration File
PSTN
PSTN(9) XROUTER REFERENCE MANUAL 18/10/2023
NAME
PSTN -- PSTN Modem Support.
DESCRIPTION
The following text describes a facility which was inherited
from DOS XRouter, but which probably has no relevance
nowadays?...
XRouter may be connected to one or more Public Switched
Telephone Network (PTSN) modems, for dial-in and dial-out
operations.
Dial-in would, for example, allow users and/or sysops to
connect to XRouter and operate it using a dumb terminal or a
standard terminal package such as Telix or Hyperterm.
Alternatively, after login, the link may be switched into
SLIP or PPP mode for TCP/IP operations, behaving in exactly
the same way as a dial-up Internet Service Provider.
Dial-out allows XRouters to be linked with each other or with
an Internet service provider, for the purposes of on-demand
wired routing, or Internet Connection Sharing.
A single modem may be used for both dial-in and dial-out
operations on the same port, although not at the same time
of course!
Suitable Modem Types
~~~~~~~~~~~~~~~~~~~~
Almost any modem is suitable, providing it can be initialised
by a single string of characters and can be configured to
disconnect when DTR is dropped.
Hardware Configuration
~~~~~~~~~~~~~~~~~~~~~~
External modems should be connected to a serial port using a
cable with at least 8 connections, namely TXD, RXD, RTS, CTS,
DTR, DSR, DCD and ground. The RI (ring indicator) connection
is not needed.
Internal modems should be configured to use a spare COM
number and IRQ.
Software Configuration
~~~~~~~~~~~~~~~~~~~~~~
Each modem requires an ASYNC interface definition in
XROUTER.CFG, with COM (or IOADDR & IRQ if non-standard)
configured for the appropriate serial port or modem card.
You should use PROTOCOL=MODEM, FLOW=1 and MTU=576.
To each "modem" interface should be attached a PORT with at
least INTERFACENUM and ID specified.
If the modem requires an initialisation string, add the
directive INITSTR=<initstring>, e.g. to set the modem into
auto answer mode use "INITSTR=ATS0=1". If you don't include
the INITSTR directive, the modem configuration is unaltered.
If your modem does not, by default, hang up when the RS232
DTR signal is dropped, you should configure it to do so by
including "&D2" in the initialisation string, for example:
"INITSTR=ATM0S0=1&D2".
Example MODEM Interface and Port Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In XROUTER.CFG:
INTERFACE=5
TYPE=ASYNC
COM=3 ; (or /dev/ttyxx for Linux)
SPEED=57600
PROTOCOL=MODEM
FLOW=1
MTU=576
ENDINTERFACE
PORT=2
ID=PSTN Modem port
INTERFACENUM=5
INITSTR=ATS0=1
ENDPORT
If you will be allowing incoming calls, you must set up a
callsign and password entry for each user in USERPASS.SYS.
Dial-in Operation
~~~~~~~~~~~~~~~~~
If you have configured the modem for auto-answer, PSTN
callers must successfully complete a callsign and password
challenge before they are allowed to use the XRouter command
interface.
The callsign must be a proper amateur radio callsign, not
a "username". If a valid callsign is not given, or if the
callsign is not found in USERPASS.SYS, or if an incorrect
password is supplied, the user is immediately disconnected.
If this sounds unforgiving, it is meant to be! It will cost
hackers the price and time delay of a separate phone call
for each attack.
If the callsign and password challenge is successfully
completed, the caller will be allowed full access to the
command shell, exactly the same as a radio caller.
XRouter will disconnect the caller after 15 minutes of
inactivity. You may initialise the modem to disconnect after
a shorter interval if necessary.
The XLINK command
~~~~~~~~~~~~~~~~~
If the caller (e.g. using NOS) wishes to establish a TCP/IP
link with XRouter, the XLINK command is used to switch the
ASCII link into SLIP ("XLINK SLIP") or PPP ("XLINK PPP")
mode.
XRouter responds with "Entering SLIP mode" or "Entering PPP
mode", and will thereafter no longer respond to ASCII
commands. SLIP or PPP mode may only be terminated by
disconnection.
In order to use SLIP or PPP modes, XRouter must have at least
a global IPADDRESS, and you must set up IP routing to the
caller's IP address on the modem port.
You could either allow each caller to use their own IP
address, and have one routing entry for each caller, or you
may choose to require all callers on a particular port to use
the same IP address (since only one may connect at any time)
and set up a single routing entry.
For example, you could tell each of your SLIP/PPP callers to
set their IP address to 192.168.73.88, which is one of the
"unregistered" addresses anyone can use. If your modem is
on port 2, you would add the following entry to IPROUTE.SYS:
route add 192.168.73.88/32 * 2 d
Which means "route datagrams for 192.168.73.88 directly on
port 2 using datagram mode".
No ARP entry is necessary for the caller, because SLIP and
PPP do not use "hardware addresses".
XLINK PPP mode
~~~~~~~~~~~~~~
XLINK SLIP mode requires no extra configuration, but PPP mode
optionally uses an extra file to configure the PPP system for
receive operations on the modem port. For example, you may
wish to use one IP address when making outgoing connects and
a different one when receiving incoming connects.
The optional file is named "PPPHOST.n" where n is the number
of the modem port, e.g. "PPPHOST.2". You may have a separate
file with a different configuration for each modem port if
required. The file should be located in the same directory
as XRouter itself and may contain any PPP configuration
command.
See the description of PPP commands for details of how to
configure PPP.
The PPP link inactivity timeout defaults to 5 mins, but can
be overridden by including the PPP IDLE command in the
PPPHOST.n file.
SEE ALSO
DIAL(1) -- Dial a PSTN Connection
DUN(1) -- Dial Up Networking Commands.
PPP(1) -- PPP Configuration Commands.
PPPHOST.n(8) -- PPP Configuration File(s)
XLINK(1) -- The XLINK Command.
XROUTER.CFG(8) -- Main Configuration File.
REST-BLOG
REST-BLOG(9) XROUTER REFERENCE MANUAL 26/9/2023
NAME
REST-BLOG -- REST Interface to Sysop's Blog.
DESCRIPTION
The sysop's blog may be operated via a REST interface.
For POST, the Content-Type: header MUST be "application/json".
This facility is incomplete. The curently available
functionality is documented in the next section.
OPTIONS
a) Retrieve List of Blog Posts:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Request-Type: GET
Request-URL: api/v1/blog/posts
If successful, the response is an un-named JSON array of
objects, each objct containing the following fields:
Name Type Description
-----------------------------------------------------------
"id" integer Article/post number.
"rcvd" string Date/time of message creation (*).
"size" integer Length of the blog text in bytes.
"from" string Callsign of the post's creator.
"subject" string Topic of the post (32 chars max)
(*) in format "Mon, 14 Sep 1997 23:47:00 GMT"
b) Retrieve a Blog Post:
~~~~~~~~~~~~~~~~~~~~~~~~
Request-Type: GET
Request-URL: /api/v1/blog/posts/{post-number}
Example: http://localhost:80/api/v1/blog/posts/21
The response payload is an un-named JSON object containing
the following fields:
Name Type Description
-----------------------------------------------------------
"id" integer Article/post number.
"rcvd" string Date/time of message creation (*).
"size" integer Length of the blog text in bytes.
"from" string Callsign of the post's creator.
"subject" string Topic of the post (32 chars max)
"text" string Body of the post (plain ASCII)
(*) in format "Mon, 14 Sep 1997 23:47:00 GMT"
c) Post a Blog Article / Reply:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Request-Type: POST
Request-URL: /api/v1/blog/posts
The payload must be a JSON object containing the following
fields:
Name Type Description
-----------------------------------------------------------
"sender" string Callsign of sender
"replyto" integer No. of msg being replied to (0=new)
"subject" string Subject of the post (32 chars max)
"text" string Body of the post (unlimited size)
Response: {"id": msg-number }
EXAMPLE
curl -X POST http://localhost:80/api/v1/blog/posts \
-H "Content-Type: application/json" -d '{\
"sender": "G8PZT", "replyto": 0, \
"subject": "test of post via REST", \
"text": "Test of blog posts via REST interface"}'
LIMITATIONS
The blog's REST interface is only a proof-of-concept at this
stage. It does not yet allow article deletion, "liking" of
articles, or retrieval of replies. Those functions will be
added in a future version
SEE ALSO
BLOG(1) -- Access Sysop's Blog.
BLOGFLAGS(7) -- Options For Sysop's Blog.
MQTT-BLOG(9) -- MQTT Interface to Blog.
MQTT-SRV(9) -- MQTT Server / Broker.
REST-NETROM
REST-NETROM(9) XROUTER REFERENCE MANUAL 26/9/2023
NAME
REST-NETROM -- REST API for NetRom Subsystem.
DESCRIPTION
Net/Rom status and information can be retrieved using the
REST API.
Requests are made using HTTP, and the data is returned in
JSON (JavaScript Object Notation) format.
The base URL for such interactions is "/api/v1/netrom".
Only HTTP "GET" requests are currently supported by the
netrom API.
OPTIONS
a) Retrieve List of Nodes:
GET /api/v1/netrom/nodes
b) Display Information for Specific Node:
GET /api/v1/netrom/nodes/{id} -
({id} is the node callsign)
c) Display List of Neighbour Routes:
GET /api/v1/netrom/routes
d) Display Information for Specific Route:
GET /api/v1/netrom/routes/{id}
e) Display List of Layer 4 Circuits:
GET /api/v1/netrom/circuits
RETURNS
If the request is successful, the HTTP response code is 200 OK
and the response payload is in JSON format, as detailed below:
a) Nodes List
The response payload is a JSON array, which may be empty.
Each array element is a JSON object which contains at least
the following fields:
Name Type Description
----------------------------------------------------
"id" string Callsign of node
"alias" string Alias of node
b) Specific Node:
The response payload is a JSON object which contains at
least the above 2 fields, plus some or all of the
following fields:
Name Type Description
----------------------------------------------------
"qual" integer NetRom "quality" metric
"rtt" number Round Trip Time in seconds (*)
"hops" integer Links between here & target (*)
"sent" integer Frames from us, addressed to that node
"rcvd" integer Frames to us, addressed from that node
"queue" integer L3 frames queued for that node
"position" string Node's position in APRS format
"locator" string Node's Maidenhead locator
"qth" string Town, county etc
"ipaddr" string 44-net IP address & bits
"tcp" integer 44-net Telnet port
"software" string Software type
"version" string Software version
(more fields to be added)
(*) Zero values of "hops" and "rtt" indicate that they
have not yet been measured.
c) Routes List:
The response payload is a JSON array, which may be empty.
Each array element is a JSON object which contains at least
the following fields:
Name Type Description
----------------------------------------------------
"id" integer Unique identifier for this route
"port" integer Port number used by this route
"call" string Callsign of neighbour node
"qual" integer Assigned NetRom "quality" of route
"sntt" number Smoothed Neighbour Trip Time in secs
"lock" bool Route is sysop-locked (true / false)
"state" string "closed", "opening", "open" or "failed"
"nodes" integer No. of nodes routed via this neighbour
The list may be modified using options in the query string.
The "port" option can be used to show only the routes
using a specified PORT, like this:
/api/v1/netrom/routes?port=2
Extra information may be displayed using the "detail"
option, either as a decimal number like this:
/api/v1/netrom/routes?detail=3
or as a comma-delimited list of mnemonics, like this:
/api/v1/netrom/routes?detail=inp,rty,arq
The extra details, their mnemonics and numbers are listed
below:
Mnemonic "l2" - L2 Parameters (+1)
Name Type Description
----------------------------------------------------
"maxframe" integer L2 "window" size
"frack" integer Frame Acknowledgement time
"paclen" integer Maximum packet length (bytes)
Mnemonic "inp" - INP3 Values (+2)
Name Type Description
----------------------------------------------------
"maxtt" integer
"thrmaxtt" integer
"maxhops" integer
"flags" integer
"thrsntt" number
"inpnodes" integer,
Mnemonic "rty" - Frame Counts and Retry Rates (+4)
Name Type Description
----------------------------------------------------
"sent" integer
"resent" integer
"rtyave" number
"rtynow" number
"rtymax" number
"rtymaxtm" integer Time when rty-max occurred
Mnemonic "rat" - Throughputs, channel load etc (+8)
Name Type Description
----------------------------------------------------
"uptime" number
"txmean" integer
"txbest" integer
"txpeak" integer
"loadave" integer
Mnemonic "arq" Automatic Route Quality Calculations (+16)
Name Type Description
----------------------------------------------------
"qualave" integer Moving average quality
"qualmin" integer Minimum quality
"qualmax" integer Maxinum quality
"qualdev" integer Standard deviation of quality
Mnemonic "tim" - Times (+32)
Name Type Description
-------------------------------------------------------
"bcrcvd" integer Time of last rcvd nodes broadcast
"lasthrd" integer Time of last received frame
d) Specific Route:
The response is a single JSON object as detailed in (c)
e) List of L4 Circuits:
The response payload is a JSON array, which may be empty.
Each array element has at least the following fields:
Name Type Description
----------------------------------------------------
"remote" string Remote address: user@node:circuit
"local" string Local L4 address + our_circuit no.
"direction" string "incoming" / "outgoing"
"service" number L4X "service number", e.g. 80=http
"state" string Connection state (see below)
"txq" number Bytes queued for transmission
"rxq" number Bytes queued for reception
"rtt" number Smoothed round trip time (ms)
"tries" number Retry count for current event
"timeout" number Layer 4 timeout interval in secs
"conTmr" number Secs left until next timeout
"chkTmr" number Secs left on chocke timer
"ackTmr" number Secs left on delayed ack timer
"remBusy" bool Remote end is busy
Connection states:
~~~~~~~~~~~~~~~~~~
0 - Disconnected
1 - Awaiting Connect ACKnowledgement
2 - Connected & ready to pass data
3 - We requested disconnect, awaiting DACK
4 - Waiting for session layer to dispose
5 - Our end wants to close after data is sent
ERROR CODES
If the request is not successful, one of the following HTTP
error codes is returned:
Code Meaning
--------------------------------------------------
400 Bad Request Invalid resource specifier
404 Not Found Specified API not found
415 Unsupported Media POST data was not JSON
500 No Resources No memory, try again later
EXAMPLES
GET /api/v1/netrom/nodes/g8pzt
GET /api/v1/netrom/routes?port=3
GET /api/v1/netrom/routes?port=4&options=255
Example Response for /api/v1/netrom/routes:
[
{
"id": 1,
"port": 4,
"call": "G8PZT",
"qual": 10,
"sntt": 0.03,
"lock": false,
"state": "open",
"nodes": 66
},
{
"id": 2,
"port": 6,
"call": "G8PZT-14",
"qual": 10,
"sntt": 0.60,
"lock": false,
"state": "open",
"nodes": 2
}
]
Example Response for /api/v1/netrom/nodes
[
{
"id": "SP2L-14",
"alias": "2LJNOS"
},
{
"id": "ZL2AQY-2",
"alias": "AQYNOD"
},
{
"id": "N2NOV-7",
"alias": "ARECS"
},
{
"id": "MB7NBA",
"alias": "BAMPTN"
}
]
Example Response for /api/v1/netrom/node/g8pzt:
{
"id": "G8PZT",
"alias": "KIDDER",
"qual": 10,
"rtt": "0.12",
"hops": "1",
"frames": 61,
"queue": 0,
"position": "5224.00N 00215.00W",
"locator": "IO82VJ",
"qth": "Kidderminster, Worcestershire, U",
"ipaddr": "44.136.16.50/32",
"tcp": 23,
"software": "XRPi",
"version": "503d"
}
Example Response for /api/v1/netrom/circuits:
[
{
"remote": "G8PZT-8@G8PZT-8:0eaa",
"local": "G8PZT-9:0001",
"direction": "incoming",
"state": 2,
"txq": 0,
"rxq": 0,
"rtt": 91,
"tries": 0,
"timeout": 120,
"conTmr": 121,
"chkTmr": 0,
"ackTmr": 0,
"remBusy": false
},
{
"remote": "VK2DOT-1@VK2DOT-1:0167",
"local": "G8PZT-4:0002",
"direction": "incoming",
"state": 2,
"txq": 0,
"rxq": 0,
"rtt": 0,
"tries": 0,
"timeout": 120,
"conTmr": 120,
"chkTmr": 0,
"ackTmr": 0,
"remBusy": false
}
]
Routes with all options
[
{
"id": 1,
"port": 6,
"call": "G8ASO-7",
"qual": 180,
"sntt": 0.00,
"lock": true,
"state": "failed",
"nodes": 0,
"maxframe": 3,
"frack": 7000,
"paclen": 256,
"maxtt": 5000,
"thrmaxtt": 10000,
"maxhops": 30,
"flags": 1,
"thrsntt": 0.00,
"inpnodes": 1,
"sent": 0,
"resent": 0,
"rtyave": 0,
"rtynow": 0.00,
"rtymax": 0.00,
"uptime": 4.4,
"txmean": 0,
"txbest": 0,
"txpeak": 0,
"loadave": 0,
"qualave": 0,
"qualmin": 0,
"qualmax": 0,
"qualdev": 0
},
{
"id": 2,
"port": 4,
"call": "G8PZT",
"qual": 10,
"sntt": 0.03,
"lock": false,
"state": "open",
"nodes": 73,
"maxframe": 3,
"frack": 7000,
"paclen": 256,
"maxtt": 5000,
"thrmaxtt": 5000,
"maxhops": 30,
"flags": 14,
"thrsntt": 0.18,
"inpnodes": 1,
"sent": 91,
"resent": 0,
"rtyave": 0,
"rtynow": 0.00,
"rtymax": 0.00,
"uptime": 98.1,
"txmean": 328,
"txbest": 2034,
"txpeak": 2034,
"loadave": 21,
"qualave": 252,
"qualmin": 252,
"qualmax": 252,
"qualdev": 0,
"bcast-rcvd": 1710514580,
"last-heard": 1710515203
}
]
SEE ALSO
REST-NETROM(9) END OF DOCUMENT
REST-PMS
REST-PMS(9) XROUTER REFERENCE MANUAL 23/3/2024
NAME
REST-PMS -- REST Interface to Personal Message System.
DESCRIPTION
The PMS may be operated via a REST interface, e.g.
using a "curl" command.
The request type is either GET (to request data from the
PMS) or POST (to write data to the PMS). For POST, the
"Content-Type:" header must be "application/json", and
the payload must be in JSON format.
This facility is incomplete. The currently available
functionality is documented in the next section.
OPTIONS
a) Retrieve List of Messages:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Request-Type: GET
Request-URL: api/v1/mail/msgs
URL Options: offset - from "start" of list, default 0
maxitems - default 500
to - callsign or category
at - Distribution, e,g GBR
from - Sender's callsign
subject - string to match in subject
fwd/rvs? - to be added?
If successful, the response is an un-named JSON array of
objects, each object containing the following fields:
Name Type Description
-----------------------------------------------------------
"id" integer Message number.
"mid" string Message ID (MID or BID)
"rcvd" integer Date/time of message reception (*1).
"size" integer Length of the message body in bytes.
"type" string Type of message: (A, P, B, E, T etc)
"status" string Message status: (R, F, U etc) (*2)
"to" string Destination address (*3)
"from" string Callsign of the message's creator.
"subject" string Message subject (32 chars max)
"links" object Contains link to read the message (*4)
(*1) in Unix time, i.e seconds since 1st Jan 1970 UTC
(*2) type and status may in future be unambiguous words
(*3) e.g. "g8pzt", "all@gbr", "g8pzt@gb7pzt.#24.gbr.eu"
(*4) e.g. {"view": "/api/v1/mail/msgs/803"}
Note that messages are listed in REVERSE order, i.e. most
recent first.
b) Retrieve a Message:
~~~~~~~~~~~~~~~~~~~~~~
Request-Type: GET
Request-URL: api/v1/mail/msgs/{msg-number}
Example: http://localhost:80/api/v1/mail/msgs/21
The response payload is an un-named JSON object containing
the following fields:
Name Type Description
-----------------------------------------------------------
"id" integer Message number.
"mid" string Message ID (MID or BID)
"rcvd" integer Date/time of message reception (*1).
"size" integer Length of the message body in bytes.
"type" string Type of message: (A, P, B, E, T etc)
"status" string Message status: (R, F, U etc) (*2)
"to" string Destination address (*3)
"from" string Callsign of the message's creator.
"subject" string Message subject (32 chars max)
"text" string Body of the message (*4)
(*1) in Unix time, i.e seconds since 1st Jan 1970 UTC
(*2) type and status may in future be unambiguous words
(*3) e.g. "g8pzt", "all@gbr", "g8pzt@gb7pzt.#24.gbr.eu"
(*4) Message body includes all RFC822 and routing headers
c) Post a Message:
~~~~~~~~~~~~~~~~~~
Request-Type: POST
Request-URL: /api/v1/mail/msgs
The payload must be a JSON object containing the following
fields:
Name Type Description
-----------------------------------------------------------
"from" string Callsign of sender
"to" string Destination (see below)
"type" string Only "P" or "B" at present
"subject" string Subject of message (32 chars max)
"text" string Body of the message
For private messages the destination may be just a callsign,
or <callsign>@<hierarchical-address>. For bulletins it may
be simply <topic> or <topic>@<distribution>. For email it is
<user>@<host>.
The response is a JSON object containing the number of the
newly created post, for example: {"id": 22}
EXAMPLE
curl -X POST http://localhost:80/api/v1/mail/msgs \
-H "Content-Type: application/json" -d '{\
"from": "G8PZT", "to": "all@gbr", \
"type": "B",
"subject": "XRouter 503 coming soon", \
"text": "New XRouter expected to be completed by Xmas"}'
LIMITATIONS
The PMS's REST interface is only a proof-of-concept at this
stage, and some details may change. More functionality will
be added in a future version
SEE ALSO
PMS(1) -- Access Personal Message System.
MQTT-PMS(9) -- MQTT Interface to PMS.
PMS(9) -- About the Personal Mesaage System
REST-WALL
REST-WALL(9) XROUTER REFERENCE MANUAL 26/9/2023
NAME
REST-WALL -- REST Interface to Message Wall.
DESCRIPTION
The message wall may be operated via a REST interface, e.g.
using a "curl" command.
The request type is either GET (to request data from the
wall) or POST (to write data to the wall). For POST, the
"Content-Type:" header MUST be "application/json", and
the payload MUST be in JSON format.
This facility is incomplete. The curently available
functionality is documented in the next section.
OPTIONS
a) Obtain List of Wall Posts:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Request-Type: GET
Request-URL: /api/v1/wall/posts
If successful, the response is an un-named JSON array of
objects, each objct containing the following fields:
Name Type Description
-----------------------------------------------------------
"id" integer Article/post number.
"rcvd" string Date/time of message creation (*).
"size" integer Length of the text portion in bytes.
"from" string Callsign of the post's creator.
"text" string Body of the post (plain ASCII)
(*) in format "1997-09-14T23:47:00Z"
b) Retrieve a Wall Post:
~~~~~~~~~~~~~~~~~~~~~~~~
Request-Type: GET
Request-URL: api/v1/wall/posts/{post-number}
Example: http://localhost:80/api/v1/wall/posts/17
The response payload is an un-named JSON object containing
the following fields:
Name Type Description
-----------------------------------------------------------
"id" integer Article/post number.
"rcvd" string Date/time of message creation (*).
"size" integer Length of the text in bytes.
"from" string Callsign of the post's creator.
"text" string Body of the post (plain ASCII)
(*) in format "Mon, 14 Sep 1997 23:47:00 GMT"
c) Post a Wall Message / Reply:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Request-Type: POST
Request-URL: /api/v1/wall/posts
The payload must be a JSON object containing the following
fields:
Name Type Description
-----------------------------------------------------------
"sender" string Callsign of sender
"text" string Body of the post (unlimited size)
The response is a JSON object containing the number of the
newly created post, for example: {"id": 22}
LIMITATIONS
The wall's REST interface is only a proof-of-concept at this
stage. It does not yet allow article deletion, "liking" of
articles, or retrieval of replies. Those functions will be
added in a future version
SEE ALSO
WALL(1) -- Access Message Wall / Guestbook.
WALLFLAGS(7) -- Options For Message Wall.
MQTT-WALL(9) -- MQTT Interface to Wall.
MQTT-SRV(9) -- MQTT Server / Broker.
REST-WX
REST-WX(9) XROUTER REFERENCE MANUAL 14/3/2024
NAME
REST-WX -- REST Interface to Weather System.
DESCRIPTION
Weather data stored on XRouter can be retrieved using the
REST API.
Requests are made using HTTP, and the data is returned in
JSON (JavaScript Object Notation) format.
The base URL for such interactions is "/api/v1/weather".
Only HTTP "GET" requests are currently supported by the
weather API.
OPTIONS
a) Retrieve List of Weather Stations:
Request-Type: GET
Request-URL: /api/v1/weather/stations
b) Retrieve Weather Data From a Specific Station
Request-Type: GET
Request-URL: /api/v1/weather/stations/{id}
{id} is a station identifier, usually callsign, or LOCAL
for observations entered into the node from a local sensor.
RETURN VALUES
If successful, the HTTP response code is 200 and the payload
contains the response in JSON format, as detailed below:
For Stations List:
The response is an anonymous JSON array of objects, each object
containing the following fields:
Name Type Description
-----------------------------------------------------------
"id" string Station id, e.g. "G8PZT" or "LOCAL"
"lat_deg" number Latitude of wx station in degrees
"lon_deg" number Longitude of wx station in degrees
"dist_km" number Distance from our node in kilometers
"dir_deg" number Direction from our node in degrees
"dt": integer Observation time, in secs since 1/1/70
For a Specific Station:
The response is an anonymous JSON object, containing the above
fields plus some of all of the following weaher data:
Name Type Description
-----------------------------------------------------------
"observed" string Date and time of observation (*1)
"pressure_mb" number Air pressure in millibars
"temperature_C" number Air temperature in degrees C
"humidity" number Relative Humidity in percent
"dewpoint_C" number Dew point in degrees Centigrade
"heat_index_C" number Heat index in deg Centigrade
"wind_chill_C" number Wind Chill in degrees Centigrade
"wind_mph" number Wind speed in miles per hour
"wind_dir_deg" number Wind direction in degrees
"gust_mph" number Wind gust speed in miles per hour
"raintoday_mm" number Total rain since midnight in mm
"rain1h_mm" number Current rainfall rate mm/hour
"rain24h_mm" number Total rain in past 24 hours in mm
"sunrise" string Sunrise time at the station hh:mm
"sunset" string Sunset time at the station hh:mm
"daylight_hours" number Hours between sunrise and set
(*1) As "dt" but human-readable e.g. 2024-03-14T15:19:59Z
For Local Sensor Only:
If there is a local weather sensor feeding XRouter, the
response containing the above fields plus some or all of the
following extra data, depending on the capabilities of the
sensor:
Name Type Description
-----------------------------------------------------------
"rain_max_mm_hr" number Maximum rain rate today mm/hour
"press_max_mb" number Maximum air pressure today
"press_min_mb" number Minimum air pressure today
"temp_max_C" number Maximum temperature today
"temp_min_C" number Minimum temperature today
"humid_max" number Maximum humidity today
"humid_min" number Minimum humidity today
"wind_ave_mph" number Moving average wind speed
"wind_max_mph" number Maximum wind speed totay
"gust_max_mph" number Maximum gust speed today
"wind_dir_ave_deg" number Moving average wind direction
"wind_run_miles" number Total wind run today, in miles
"light_w_sqm" number Current light level, watts/sq m
"light_max_w_sqm" number Maximum temperature today
"UV_index" number Current UV index
"UV_index_max" number Maximum UV index today
("today" means since midnight GMT)
ERROR CODES
400 Bad Request Invalid resource specifier
404 Not Found Specified API not found
415 Unsupported Media POST data was not JSON
500 No Resources No memory, try again later
EXAMPLES
a) Stations List:
[
{
"id": "LOCAL",
"lat_deg": 50.0935,
"lon_deg": -5.0850,
"dist_km": 0,
"dir_deg": 0,
"dt": 1710395654
},
{
"id": "G8PZT",
"lat_deg": 52.2400,
"lon_deg": -2.1500,
"dist_km": 0,
"dir_deg": 0,
"dt": 1710394799
}
]
b) Specific Station:
{
"id": "G8PZT",
"lat_deg": 52.2400,
"lon_deg": -2.1500,
"dist_km": 0,
"dir_deg": 0,
"dt": 1710425999,
"observed": "2024-03-14T15:19:59Z",
"temperature_C": 13.3,
"humidity": 51,
"dewpoint_C": 3.5
"wind_mph": 0.0,
"wind_dir_deg": 202,
"gust_mph": 1.0,
"sunrise": "07:25",
"sunset": "19:12",
"daylight_hours": 11.78
}
c) Local Weather
{
"id": "LOCAL",
"lat_deg": 50.0875,
"lon_deg": -5.075,
"dist_km": 0,
"dir_deg": 0,
"dt": 1710395899,
"observed": "2024-03-14T06:58:19Z",
"pressure_mb": 1006,
"temperature_C": 10.9,
"humidity": 94,
"wind_mph": 16.6,
"wind_dir_deg": 147,
"gust_mph": 20.6,
"rain_max_mm_hr": 0,
"press_max_mb": 1010.1,
"press_min_mb": 1005.9,
"temp_max_C": 11,
"temp_min_C": 10.6,
"humid_max": 95,
"humid_min": 94,
"dewpoint_C": 9.7,
"wind_ave_mph": 11.6,
"wind_max_mph": 23.3,
"gust_max_mph": 34.4,
"wind_dir_ave_deg": 139,
"wind_run_miles": 58.2,
"light_w_sqm": 0,
"light_max_w_sqm": 0,
"UV_index": 0,
"UV_index_max": 0,
"sunrise": "07:35",
"sunset": "19:25",
"daylight_hours": 11.83
}
SEE ALSO
WX(1) -- Display Weather Information.
WXFILE(7) -- Weather Import File.
WX(9) -- Weather Information System.
WX-SVC(9) -- NetRomX Weather Service
RIP
RIP(9) XROUTER REFERENCE MANUAL 18/10/2023
NAME
RIP -- Routing Information Protocol.
DESCRIPTION
Routing Information Protocol (RIP) allows IP routers to learn
about each other's routing, similar to the way that NetRom
exchanges nodes broadcasts.
There are various versions of RIP, and XRouter currently
implements RIP2 and RIP98. RIP2 is used for the IPEncap-based
"44-net" network, and RIP98 was developed by G8BPQ specically
for radio-based routers. If there is a need for other
flavours of RIP, they may be included in a later version.
RIP98 works by sending its routing table to nominated peers
at regular intervals, and accepting routing information from
peers. The routes learned by this means are added as
temporary entries to the IP routing table. These entries
have a finite lifetime, and if not updated regularly they
drop out of the routing table.
Configuring XRouter to use RIP98
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following configuration commands are available:
RIP ACCEPT Remove a peer from the refuse list.
RIP ADD Add a peer to the broadcast list. (*)
RIP DROP Remove a peer from the broadcast list.
RIP LEARN Allow / disallow route learning. (*)
RIP REFUSE Ignore broadcasts from a peer. (*)
RIP STATUS Show status of RIP.
RIP TIMEOUT Specify lifetime of learned routes. (*)
Commands marked (*) may be used in BOOTCMDS.SYS or
IPROUTE.SYS to configure the system automatically.
By default, RIP98 route learning is OFF, so you need to
include at least a "RIP LEARN ON" command, to enable your
system to learn routes from others. Your neighbours also
need to add your IP address to their RIP broadcast lists.
If you wish to inform your neighbours of your existence and
your routing capabilities, you need some RIP ADD commands,
one for each neighbour to whom you wish to send RIP updates.
If you have LEARN enabled, and there is a neighbour who is
sending unwanted RIP updates to you, you may ignore them
using RIP REFUSE.
The RIP commands are explained in more detail in section 1 of
this manual.
SEE ALSO
RIP(1) -- Routing Interface Protocol Commands.
RLOGIN
RLOGIN(9) XROUTER REFERENCE MANUAL 21/10/2023
NAME
RLOGIN -- Remote Login.
DESCRIPTION
RLOGIN is a "remote login" facility for sysops only.
The secure password challenge/response mechanism, using
the "@" command, is inconvenient for frequent use, and
unnecessary in cases where the remote sysop can access
the router via a "secure" link such as a wire link between
two systems. RLOGIN provides a connection with a plain
text password system for these situations.
RLOGIN uses a Telnet connection to TCP port 513. This
port may be moved or disabled using the RLOGINPORT
directive in XROUTER.CFG if required.
Upon connection, the sysop is prompted to enter his
callsign, and is then asked for his password. If the
two match with an entry in PASSWORD.SYS, the sysop is
granted access with full sysop status.
FILES
The following files affect the operation of RLOGIN. They
must be located in the same directory as the XRouter program:
PASSWORD.SYS is where the sysops' passwords are stored.
XROUTER.CFG is where RLOGINPORT is specified.
CAVEATS
Needless to say, this facility should *NEVER* be used
over a radio link, otherwise someone will see the
password.
Connections to the RLOGIN service are not considered secure
if they are via 44-net, because the packets may have
travelled across RF, or via another Amateur's system. In
that case, certain functions, such as the NFTP client are
not allowed.
SEE ALSO
PASSWORD.SYS(8) -- Sysop Password File.
RLOGINPORT(7) -- TCP Port for RLOGIN.
XROUTER.CFG(8) -- Main Configuration File.
SCRIPT
SCRIPT(9) XROUTER REFERENCE MANUAL 17/10/2023
NAME
SCRIPT -- Dialer Scripts
DESCRIPTION
Assuming you have a port configured for modem use, DUN
requires at least one dialler script, to control the dial and
login sequence.
Dialler scripts are ordinary text files containing script
commands as detailed below, one per line. Lines must not
exceed 256 characters in length. The script file can be named
as you wish, for example you might like to name your AOL dial
script "AOL.SCR". You will need to use this name later to
identify the script, so it makes sense to call it something
meaningful, rather than "SCRIPT1.TXT". Script files must
reside in the same directory as the XRouter executable.
DUN Script Commands Overview
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
CONTROL Raise / lower RS232 DTR signal.
MODE Protocol to use upon successful login.
PPP PPP configuration commands.
SEND Send text.
SLEEP Temporary pause.
WAIT Wait for text in received data.
DUN Script Commands In Detail
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
CONTROL - Raise / Lower RS232 DTR signal.
Syntax: C[ontrol] <up | down>
The CONTROL command is used to raise or lower the
RS232 DTR (Data Terminal Ready) line. Most modems
require the DTR signal to be "up", and will disconnect
or reset when it goes down. Those modems which do not
do this by default can usually be configured to do so
by including "&D2" in the initialisation string.
MODE - Set protocol to use upon successful login.
Syntax: M[ode] <kiss | ppp | slip>
Example: MODE PPP
MODE specifies the protocol to use after your system
has logged into the remote host, i.e. when the script
ends without error. It must precede the dialling and
login sequence, and any protocol dependent commands,
such as the PPP commands.
PPP - PPP configuration commands.
Syntax: P[pp] <idle | ipcp | lcp | log | pap> [arg]
Example: PPP IDLE 300
PPP commands are used to configure the PPP subsystem
for the connection being established. Note that
within DUN scripts the <port> argument is omitted
because XRouter knows which port the script is using.
SEND - Send a line of text.
Syntax: S[end] <text>
Example: SEND ATDT01674302153
The SEND command sends one line of text to the modem
or the remote host, for example modem initialisation
and dial commands, or login commands. The <text>
argument may contain spaces, and the system will
append a carriage return/line feed.
SLEEP - Temporary pause.
Syntax: SL[eep] <millisecs>
Example: SLEEP 5000
The SLEEP command causes the script to pause for the
specified interval. For example, you would need a
short delay after issuing a modem reset command
before any more commands would be accepted by the
modem. When the pause is complete, script execution
continues on the next line.
WAIT - Wait for received text.
Syntax: W[ait] <millisecs> <string> [exiterr]
Example: WAIT 5000 Password: exiterr
WAIT causes XRouter to wait for specific responses
from the modem or remote host. <millisecs> specifies
the maximum wait interval. <string> specifies the
string of characters (20 chars max, no spaces) to wait
for.
When the string is seen in the received data stream,
the next script command is executed.
If "exiterr" is present, the script will abort if the
string is not seen before the interval expires. If
not present, the next script command will be executed
upon timeout.
Dial up networking may be administered "on the fly" using the
DUN command , which is detailed in the sysop command reference
section. The DUN ADD and DUN LOG commands may also be used in
IPROUTE.SYS and / or BOOTCMDS.SYS to configure the system at
boot time.
Example DUN script
~~~~~~~~~~~~~~~~~~
; Xrouter DUN script for establishing PPP connection with ISP
;
; Upon connection, the ISP sends some greetings text, then
; "Login:", and waits for login name.
;
; Upon receiving the login name it sends "Password:" and
; waits for the caller to send the password.
;
; Upon receiving the password, the ISP sends
; "Entering PPP mode".
;
;
; Drop DTR to reset any modem error condition
control down
;
; Wait for 1 sec
sleep 1000
;
; Raise DTR to allow normal operation
control up
;
; Specify the mode to use after link is established
mode ppp
;
; ISP requires PAP authentication: username=gb7pzt,
; password=bsfjflavs
ppp pap user gb7pzt bsfjflavs
;
; Get the modem's attention
send AT
;
; Wait for up to 5 secs for an "OK" response. Abort if none
wait 5000 OK exiterr
;
; Modem is awake. Dial the ISP
send ATDT01905643000
;
; Wait for up to 1 minute for the "user:" login prompt
wait 60000 user exiterr
;
; Prompt obtained. Send username
send gb7pzt
;
; Don't bother waiting for "password:" prompt, just send
; it after 1 sec.
sleep 1000
send bsfjflavs
;
; Wait for confirmation of entry to PPP mode
wait 30000 PPP exiterr
;
; ISP is now in PPP mode. XRouter will enter PPP mode when
; script ends
;
SEE ALSO
DIAL(1) -- Dialer
DUN(1) -- Dial Up Networking commands
DUN(9) -- Dial Up Networking
SERVERS
SERVERS(9) XROUTER REFERENCE MANUAL 21/10/2023
NAME
SERVERS -- Servers Available in XRouter.
DESCRIPTION
In the XRouter context, servers are processes which accept
connections or data from users (i.e. clients) and provide
specific services (e.g. file transfer) to those clients.
They are often associated with a specific TCP or UDP "service
port" number, for example TCP port 21 for file transfer, UDP
port 53 for DNS server and so on.
XRouter contains a number of servers and makes them available
by default, although they may be disabled by the sysop if
desired.
The policy of making services available by default is an
attempt to provide useful services to the Amateur Radio
Packet Network (amprnet) with minimal effort on the part of
the sysop. If services were disabled by default, most sysops
wouldn't enable them, either because they didn't understand
them, or because they couldn't be bothered.
Access to the benign servers is unrestricted, but most are
protected by password and IP access control lists.
The following servers are available in XRouter
Name Port Proto Function
---------------------------------------------------
ECHO 7 TCP Echoes data back
DISCARD 9 TCP Discards data
FTP 21 TCP File Transfer
TELNET 23 TCP User session
DNS 53 UDP Domain Name System
FINGER 79 TCP User information
HTTP 80 TCP Web server
TTYLINK 87 TCP Keyboard to Keyboard chat
RLOGIN 513 TCP Remote Login (sysop)
SOCKS 1080 TCP SOCKS Proxy
APRS 1448 TCP Serves APRS data
MQTT 1883 TCP Message Queue Telemetry Transport
TELPROXY 2323 TCP Raw TCP to AX25 bridge
CHAT 3600 TCP Conferencing
AGWHOST 8000 TCP AGW Packet Engine emulator
RHP 9000 TCP Remote application support
HAMLIB - TCP HamLib Emulator
RIGSRV - TCP Radio control server
PMS - - Personal Mail Server
For details of how to move the above ports or disable the
servers, please see the TCP-PORTS page.
Brief Overview Of XRouter Servers
=================================
ECHO
~~~~
Anything the user sends is echoed back to him. This is a
useful tool for test purposes. This server is also available
from the command prompt, and as NetRomX service 7.
DISCARD
~~~~~~~
This simply dumps anything sent to it. It is another useful
tool for test purposes. This server is also available from the
command prompt, and as NetRomX service 9.
FTP
~~~
Allows sysops to upload, download, move and rename files,
create and remove directories etc. Not available to users.
TELNET
~~~~~~
Provides regular user access to the XRouter command prompt.
Also available as NetRomX service 23.
DNS
~~~
Answers Domain Name System (DNS) queries, to provide a
hostname to IP-address translation service.
FINGER
~~~~~~
Allows users to retrieve information about other users or any
other topics provided by the sysop. This server is also
available from the command prompt, and as NetRomX service 79.
HTTP
~~~~
Serves HTML (web) pages, and provides a browser interface to
XRouter. Can be made available on both XRouter and host
system TCP stacks, plus NetRomX service 80.
TTYLINK
~~~~~~~
For direct keyboard to keyboard chat. Als avaiable on NetRomX
service 79.
RLOGIN
~~~~~~
Secure remote login for sysops only, providing full syop-mode
access.
SOCKS Proxy
~~~~~~~~~~~
Circuit level proxy allowing applications to access external
services through a firewall as an alternative to NAT.
APRS
~~~~
Shares APRS data between clients such as UI-View, RF ports
and the Internet APRS-IS systems. Can be made avaiable on
both XRouter and host TCP stack, plus NetRomX service 14.
MQTT
~~~~
Machine to machine information broker using a publish /
subscribe paradigm. Allows sending and receiving of raw KISS,
AX25, NetRom, XRChat etc, plus status / event information.
Can be used to develop modern user interfaces. Available on
Linux TCP stack only. Also available, with restrictions, via
NetRomx service 1883.
TELPROXY
~~~~~~~~
The Telnet Proxy server allows TCP/IP applications to make
fully transparent raw binary connections (i.e. ones capable of
handling compressed forwarding) to AX25 or NetRom
destinations.
CHAT
~~~~
Allows groups of users to hold conferences, either locally or
globally via a network of interconnected servers. Also on
NetRomX service 8.
AGWHOST
~~~~~~~
Emulates the AGW TCP host interface, enabling XRouter to
support applications (e.g. UI-View) that were designed for
use with the AGW Packet Engine.
RHP
~~~
Allows XRouter to support a wide range of applications which
may be located on the same PC or remotely, using a
socket-like paradigm.
PMS
~~~
A no-frills mailbox which can handle both private mail and
bulletins. It is available from AX25 and the XRouter command
prompt, but currently has no TCP port of its own. Available
as NetRomX service 2.
HAMLIB
~~~~~~
Emulates the HamLib rig control interface, for use with
applications that are designed to use Hamlib. Available
only on Linux TCP/IP stack. Useful only when XRouter is
controlling rigs.
RIGSRV
~~~~~~
Another radio control interface (private project).
Available only on Linux TCP/IP stack. Useful only when
XRouter is controlling rigs.
SEE ALSO
CHAT-SRV(9) -- Chat Server
DISCARD(1) -- Start a Sink Session
ECHO(1) -- Start an Echo Session
FINGER(1) -- Display User Information
TCP-PORTS(6) -- TCP Server Ports
SERVICES
SERVICES(9) XROUTER REFERENCE MANUAL 22/10/2023
NAME
SERVICES -- NetRomX Standard Services.
DESCRIPTION
G8PZT extended NetRom at the turn of the century to create
"NetRomX". This uses an alternative L4 connect request, with
opcode 8, and the mnemonic "CREQX". This type of request
includes a 16-bit "service number", and can therefore request
connection to any of 65536 separate types of process on the
target system.
This is a major improvement over "standard" NetRom, which only
allowed a node to host a maximum of 16 L4 services, one per
SSID. This was not just a barrier to the development of novel
services... In order to be connectable via L4, every such SSID
had to be in everyone's nodes tables. And there was no
agreement on which SSID should represent which service.
With NetRomX there is no need to clutter the nodes tables with
SSID's, because every service has a STANDARD number, as shown
in the table below:
No. Service Description
------------------------------------------------------------
0 CMD Normal connection to Node's command line
1 INFO Standard Information server
2 PMS Personal Message System
3 BBS (reserved for Bulletin Board System)
4 DX (reserved for DX cluster/dx-spot feed)
5 TPP (reserved for "Tampa Ping-Pong" chat)
7 ECHO Echoes data back to sender
8 CHAT XRChat server
9 DISCARD Data sink
10 RMS (reserved for winlink RMS}
11 BPQCHAT (reserved for BPQ chat server)
13 DAYTIME Local date/time (similar to RFC867)
14 APRS APRS Server
15 CUSTINF (reserved for custom information file server)
16 WX Local weather information
17 TELEM (reserved for Telemetry server)
18 SMS Short Message System server
19 CHARGEN Generates a test pattern
20 NDATA (reserved for NFTP extension)
21 NFTP Netrom File Transfer Protocol
22 NSSH (reserved for secure login - if legal?)
23 TELNET Normal L4 login (same as 0)
25 SMTP (reserved for Simple Mail Transfer Protocol)
26 MHEARD MHEARD server (shows MH lists)
27 DXLIST DX List server (shjows DX lists)
79 FINGER Finger server
80 HTTP NetromWeb (HTTP over Netrom) server
87 NTTY Netrom TTY - Keyboard to keyboard chat
1883 MQTT MQTT server
If you know that the target system is XRouter (usually they
have "XR" in the alias), you can be sure that if their PMS is
enabled, it will be on service 2.
Standard services facilitate simple commands such as
"TIME <nodecall>", to discover the local time, time zone and
daylight saving status at a distant node. Or "PMS <nodecall>"
to connect directly to someone's PMS.
It is envisaged that some of the services may be used by
network crawlers (human and machine) to harvest data without
needing to know the exact format of the commands on all the
different types of software.
SEE ALSO
APRS-SVC(9) -- APRS Service.
CHARGEN(9) -- Character Generator Service.
CHAT-SVC(9) -- Chat Service.
DAYT-SVC(9) -- DAYTIME Service.
DX-SVC(9) -- DX Service
DISC-SVC(9) -- Discard Service
ECHO-SVC(9) -- Echo Service.
HTTP-SVC(9) -- HTTP Service.
INFO-SVC(9) -- Information Service.
MH-SVC(9) -- MHeard Service
MQTT-SVC(9) -- MQTT Service
NFTP-SVC(9) -- Netrom File Transfer Service.
NTTY-SVC(9) -- NetromTTY Service.
PMS-SVC(9) -- Personal Message Service.
SMS-SVC(9) -- Short Message Service
TCP-PORTS(6) -- TCP Server Ports
WX-SVC(9) -- Weather Service.
SLIP
SLIP(9) XROUTER REFERENCE MANUAL 19/10/2023
NAME
SLIP -- Serial Line IP.
DESCRIPTION
SLIP is a very simple protocol which encapsulates Internet
Protocol (IP) datagrams for transmission over serial (e.g.
RS232) lines. It is defined in RFC 1055.
The SLIP protocol specifies the following special characters:
Name Hex Dec Purpose
---------------------------
FEND 0xC0 192 Frame End
FESC 0xDB 219 Frame Escape
The FEND characters mark the start and end of the frame
containing the encapsulated datagram as follows:
.------.-------------.------.
| FEND | IP Datagram | FEND |
'------'-------------'------'
In order to ensure that the FEND character only occurs at the
start and end of the frame, FENDs which occur within the
unencapsulated datagram are "escaped" to the two byte sequence
FESC 220. Likewise FESC is escaped to the sequence FESC 221.
It is permissible for two datagrams to share a FEND:
.------.-------------.------.-------------.------.
| FEND | IP Datagram | FEND | IP Datagram | FEND |
'------'-------------'------'-------------'------'
Serial Line Parameters
~~~~~~~~~~~~~~~~~~~~~~
Serial lines used for SLIP must run at 8 data bits. Flow
control must be hardware or none, as XON/XOFF flow control
would interfere with the protocol.
If flow control is used, the cable must contain at least 5
cores, namely TXD, RXD, RTS, CTS and GND. If flow control is
not used, only TXD, RXD and GND are required.
In all cases, a NULL MODEM is required. In the case of "real"
RS232 this could be an actual null modem device, or a cable
that is wired such that the TXDs at each end go to the RXDs
at the other end, and the RTSs at each end go to the CTSs at
the other. "Virtual" COM port pairs such as Com0Com
(Windows) or tty/pty pairs (Linux) include this functionality
as standard.
Configuring a SLIP Link
~~~~~~~~~~~~~~~~~~~~~~~
SLIP can be used to link XRouter with other IP systems (e.g.
NOS) via real or virtual COM ports. A typical configuration
in XROUTER.CFG would be as follows:
INTERFACE=13
TYPE=ASYNC <-- Serial RS232
COM=13 <-- COM number / device
PROTOCOL=SLIP <-- Use SLIP
SPEED=38400 <-- Baud rate
FLOW=0 <-- No flow control
MTU=1500 <-- Allows largest IP
ENDINTERFACE
PORT=3
ID=SLIP Link to BBS
INTERFACENUM=13
ENDPORT
Unless overridden with a port IPADDRESS statement, the SLIP
link will use XRouter's "core" IP address, i.e. the one
specified by the global IPADDRESS. This is usually a 44-net
address.
Remember to set up an IP ROUTE entry for the neighbour system
via this PORT number, e.g. if the neighbour's IP address is
44.131.91.2, the following entry routes traffic to it via
port 3 using datagram mode:
IP ROUTE ADD 44.131.91.2 * 3 d
Note that "virtual circuit" (v) and "netrom" (n) routing
modes can not be used here.
A SLIP link thus created does not involve the Windows or
Linux IP stack in any way, therefore there is no restriction
on the protocols that can be carried within the IP datagrams.
For example you may create an AX25 link using AXIP, or tunnel
traffic over the link using IPEncap.
SLIP was largely replaced by PPP long ago, but the beauty of
it is its simplicity. It is so easy to configure, and only
requires a pair of COM ports and a 3 core cable.
Temporary SLIP
~~~~~~~~~~~~~~
A dial-in MODEM connection may be switched into SLIP mode for
the remainder of the call using the "XLINK SLIP" command,
thus emulating an old-fashioned dial-up ISP.
This may possibly be of use for controlling remote sites that
have telephone lines but no Internet connection. Or even as
a backup in case an Internet connection breaks down (cheap
routers and switches fail!). See the manual entry for PSTN
for more details.
SEE ALSO
IP(1) -- IP Routing / Configuration Commands.
IPROUTE.SYS(8) -- IP Configuration File.
KISS(9) -- KISS Protocol.
XLINK(1) -- Establish a Temporary SLIP / PPP Interlink
XROUTER.CFG(8) -- Main Configuration File.
SMS-SVC
SMS-SVC(9) XROUTER REFERENCE MANUAL 7/9/2023
NAME
SMS-SVC -- Short Messaging Service
DESCRIPTION
This short messaging service is for XRouter sysops, and has
nothing to do with telephone SMS. It uses NetRomX service
number 18.
The purpose of this service is to receive short, single-line
messages (up to 160 characters), and to deliver them to the
sysop.
Although the protocol is plain text, it is intended for use
by automatons, not humans.
It is a one-way protocol. Nodes "push" messages to each
other, by connecting to each other's SMS service. They
cannot poll for mail.
The protocol is not yet finalised. It works, but may need to
be tweaked.
Line endings conform to the "packet radio" standard, i.e.
ASCII 13 (carriage return) only.
Upon connection to the server, the client receives a greeting
together with a "nonce" for authorisation purposes:
G8PZT-1 SMS ready [34564287]
The client must then respond with an authorisation string,
calculated from the nonce:
A 0xxxx<authstring>
An invalid authorisation string, or any other response at
this point results in disconnection. 0 is the version.
Once authorised, there are only 3 possible commands, namely
S, R and Q.
The S command sends an SMS to the server:
S <to> <from> <stamp> <text>
<to> and <from> are callsigns
<stamp> is the msg timestamp in secs since 1/1/70
<text> is up to 160 characters of plain text.
The R command sends a "read receipt" to the server,
indicating that the recipient has read the message:
R <to> <from> <stamp> <rstamp>
<to> and <from> are callsigns
<stamp> is the msg timestamp in secs since 1/1/70
<rstamp> is the timestamp of when the message was read
The client may send multiple S and R messages in one session.
When the client is done, it sends Q (quit), and the server
closes the connection.
The sysop is alerted to the presence of an unread mesage by
a flashing "S" on the top status bar. He can then type "SMS"
to view the messages.
SEE ALSO
SMS(1) -- Short Messaging System for Sysops.
SERVICES(9) -- NetRomX Standard Services.
SOCKS
SOCKS(9) XROUTER REFERENCE MANUAL 27/9/2023
NAME
SOCKS -- SOCKS Proxy Server.
DESCRIPTION
The purpose of the SOCKS proxy server in XRouter is long
forgotten.
It was included in XRouter either to allow users on amprnet
to view Internet web pages, or to allow a LAN browser to
gain a 44.x.x.x source address, to view amprnet web sites.
What is SOCKS?
~~~~~~~~~~~~~~
SOCKet Secure (SOCKS) V4 is a protocol that acts as a circuit
level proxy for applications, routing traffic between a client
and server through a proxy server. It was intended for
accessing external services through a firewall, as an
alternative to using NAT (Network Address Translaton).
SOCKS5 is defined in RFC 1928, and is an extension of the
SOCKS4 protocol. It offers more choices of authentication,
adds support for IPv6 and UDP that can be used for DNS
lookups.
XRouter implements both SOCKS V4 and V5. The implementation is
functional but incomplete.
How it Works
~~~~~~~~~~~~
A SOCKS proxy acts as both client and server simultaneously.
A user client makes a TCP connection to the the socks server,
and communicates with it using the SOCKS protocol. The user
instructs the SOCKS proxy to connect to the target server,
from which point onwards the proxy becomes the client of the
target server.
.---------.
.--------. 62.31.1.3 | XRPi | 44.131.91.1 .--------.
| server |-----<------| SOCKS |-------<-----| client |
'--------' | proxy | '--------'
83.1.24.5 '---------' 44.131.91.2
The above diagram depicts an amprnet client (44.131.91.2)
connected to an Internet server (83.1.24.5) via a SOCKS proxy.
On the amprnet side XRouter is using the amprnet address
44.131.91.1, and on the Internet side it is using the Internet
address 62.31.1.3.
As far as the target server is concerned, it is talking with
62.31.1.3, whilst the user client is connected to 44.131.91.1.
Anything sent by the client is relayed to the server by the
proxy and vice versa.
Client Requirements
~~~~~~~~~~~~~~~~~~~
Client programs for use with this proxy must have SOCKS client
capability. Programs such as Internet Explorer, Firefox, and
many other have this capability.
Access Control
~~~~~~~~~~~~~~
The "rules" to control which destinations are allowed to be
accessed via the SOCKS proxy are contained in the SOCKS.ACL
file.
The rules allow you to specify which destination IP
addresses and TCP ports may be accessed by specified
source IP ranges.
If the file is not present, or contains no valid rules, all
destinations are blocked. Attempting to access a blocked
destination causes the proxy to return an "access denied"
code.
Configuration
~~~~~~~~~~~~~
The server is available by default, and requires no setting
up, other than the IP routing and egress control.
The server's TCP port may be changed, or the server disabled,
by using the SOCKSPORT=n directive in XROUTER.CFG. Setting
the port to zero disables the server.
FILES
SOCKS.ACL, XROUTER.CFG
SEE ALSO
ACCESS.SYS(8) -- TCP/IP Access Control List.
NAT(9) -- Network Address Translation.
SOCKS.ACL(8) -- SOCKS Egress Control List
SOCKSPORT(7) -- TCP Port for SOCKS Proxy.
XROUTER.CFG(8) -- Main Configuration File
STATS
STATS(9) XROUTER REFERENCE MANUAL 3/1/2024
NAME
STATS -- Explanation of Output of STATS Command.
SYNOPSIS
This document attempts to explain some of the responses
produced by the "stats" command.
SUMMARY PAGE
Entering S[tats] without arguments produces a single page
containing the following fields (values removed to make the
display fit the page):
Time active (mins):
Overruns:
Memory blocks: Min/Cur/Max
Nodes: Cur/Max/free/poss
Total bytes sent/rcvd:
Ccts/MaxCcts L2/L3/L4/TCP:
HTTP Rqst/Srvd/Bytes/Prxyd
IP Heard/Reasm/Rcvd/Routed:
IP Bad Hdr/Chksum/Version:
IP Sent/Frag/Unsent/Total:
L4 Connects Tried/Made/Rcvd:
L4 total frames Sent/Rcvd:
L4 Info Snt/Rcvd/Resent/Reseq:
L4 Choke Snt/Rxd RSET Snt/Rxd:
L4 Timeouts/Failures:
L3 Frames Hrd/Rcvd/Sent/Rlyd:
"Time active" is the elapsed time in minutes since XRouter
was last restarted. Also shown are day, hours,
minutes and seconds.
"Overruns" is nothing to worry about. It is a measure of how
fast the main code is being executed. Expect low
overruns on a fast machine and higher overruns when
there is a lot of console scrolling.
"Memory blocks" shows the minimum, maximum and current number
of allocated memory blocks.
"Known nodes" is the number of nodes in the table. "Cur" is
the current figure, "Max" is the maximum, "Free" is
the number of free table slots currently available,
and "Poss" is the number of nodes the table might
contain if it was not limited in size. If this last
figure is higher than "max", it indicates that the
table is not big enough, which may cause loss of low
quality and "stale" entries in favour of better ones.
"Total bytes sent/rcvd" are the total bytes sent and received
by all the ports. They include all ax25 overhead.
"Ccts/MaxCcts" shows the current and highest number of
simultaneous circuits that have been active at any
time. Separate figures are shown for Ax25 levels 2,
3 and 4, and TCP/IP.
"HTTP Rqst/Srvd/Bytes/Prxyd" shows the total number of HTTP
requests received and served, the number of bytes
served, and the number of requests that were proxied,
i.e. handled on behalf of another system.
"IP Heard/Reasm/Rcvd/Routed" shows the total number of IP
frames heard (i.e. addressed to us and to others),
reassembled from fragments, received (i.e. addressed
to us), and routed to others.
"IP Bad Hdr/Chksum/Version" shows the number of IP frames
ignored due to corrupt IP headers (e.g. too short to
be a legal IP frame), checksum mismatch, and
incompatible IP version.
"IP Sent" is the no. of IP datagrams originated by XRouter,
i.e. not routed from somewhere else. "Frag" is the
number of datagrams which had to be fragmented to fit
a link. "Unsent" is the number of datagrams which
couldn't be sent due to low memory or no route, and
"Total" is the total number of datagrams or fragments
thereof which were transmitted.
"L4 Connects Tried/Made/Rcvd" shows the total number of
outgoing and incoming AX25 level 4 connections.
"Tried" is the number of requests initiated, "Made"
is the number which were successful, and "Rcvd" is
the number of incoming connects.
"L4 total frames Sent/Rcvd" shows the total number of NetRom
level 4 frames of all types sent and received by
XRouter.
"L4 Info Snt/Rcvd/Resent/Reseq:" shows the totals for NetRom
level 4 information-bearing frames. "Snt" is the
number of frames originated by us. "Rcvd" is the
number of frames addressed to us. "Resent" shows how
many were re-transmitted because no ack was received.
"Reseq" is the number of frames that re-sequenced,
i.e. were received out of sequence but subsequently
used when the missing frames arrived.
"L4 Choke Snt/Rxd RSET Snt/Rxd:" counts the number of NetRom
level 4 choke and RESET frames sent and received by
XRouter. A sent choke indicates that we are
receiving L4 data faster than we can process it, and
instructs the other end to back off for a while. A
received choke indicates that we are sending data too
fast for the other end of the link to handle. Note
that these figures do not necessarily indicate that
there is something wrong with XRouter's links, as
they apply to the "virtual circuit" from one process
to another, which may span many intervening nodes.
L4 resets are sent when frames are received for
non-existent circuits.
"L4 Timeouts/Failures" shows the number of times the NetRom
level 4 T1 timer timed out while waiting for an ack,
causing re-transmission of a frame. "Failures" shows
the number of level 4 circuits which were aborted due
to excessive retries.
------------------------------
Entering "S[tats] *" produces the above followed a set of
PORT stats, then a set of INTERFACE stats.
------------------------------
Note that the L4, TCP and IP stats may be displayed in
isolation using "S L4", "S TCP", and "S IP".
IP-ERRORS
In addition to the normal IP stats shown above, "S[tats] IP"
shows a set of IP error counters as follows:
IP NoRoute NoGatewy RouteLoop:
IP Ignored Rejected Discarded:
IP Denied TTLExpired NoSocket:
IP TooBig HostEncap XrEncap:
IP HdrParam Recursion:
"NoRoute" means that a datagram was dropped because there was
no suitable route in the IP routing table, or the
route pointed to a non-existent PORT.
"NoGatewy" means that there is no suitable gateway for an
encapsulated datagram.
"RouteLoop" means that the route for an encapsulated datagram
is back to the gateway it came from.
"Ignored" means received datagrams ignored because they were
on the same subnet as XRouter, but not addressed to
it. Not an error, just info.
"Rejected" means frames rejected because they matched an IP
route entry of type "r" (reject). Unless IP QUIET is
set, these elicit an ICMP resonse of HOST UNREACHABLE.
"Discarded" means datagrams dropped because they matched an
IP route entry of type "s" (silent discard). No ICMP
response is sent.
"Denied" means datagrams carrying TCP that were droppped
because they failed XRouter's access control rules.
"TTLExpired" means datagrams that couldn't be routed because
their Time To Live counter had expired.
"NoSocket" counts datagrams dropped because they were the
wrong protocol for a route mode of "k" (kernel).
"TooBig" means datagrams rejected because they were too large
for the outgoing MTU and had the DF (don't fragment)
option set. Unless IP QUIET is set, these elicit an
ICMP response of "fragmentation needed".
"HostEncap" counts encapsulated datagrams (IPIP, IPENCAP,
IPUDP) that were suupposed to be routed via the
operating system's IP stack, but failed to do so.
"XrEncap" counts encapsulated datagrams (IPIP, IPENCAP,
IPUDP) that were suupposed to be routed via XRouter's
own IP stack, but failed to do so.
"HdrParam" means datagrams dropped due to a problem in their
IP header parameter lists.
"Recursion" counts datagrams that were dropped because they
traversed the IP stack too many times.
AXIP STATS
These are displayed using "S[tats] AXIP".
total frames heard
frames ignored (too short)
frames ignored (bad CRC)
frames ignored (unsolicited)
valid frames received
frames sent
frames unsent (resolution failure)
frames unsent (no route)
frames unsent (routing loop)
frames unsent (miscellaneous reasons)
"Total frames heard" includes valid AXIP plus all other frames
heard on the interface.
"Too short" are received frames too short to be legal AXIP.
"Bad CRC" are received frames long enough to be legitimate
AXIP, but failed the CRC test.
"Unsolicited" are valid AXIP from unrecognised senders.
"Valid frames received" are the ones accepted into AX25.
"Resolution Failure" occurs when IPLINK has been specified as
a hostname, but that hostname can't be resolved to an
IP address.
"No Route" occurs when there is no IP route which can handle
the encapsulated packet.
"Routing loop" occurs when the IP routing is set up
incorrectly, causing the encapsulated packet to be
encapsulated again ad infinitum.
"Miscellaneous Reasons" usually indicates a temporary IP
routing problem, such as a loose plug.
AXUDP STATS
These are displayed using "S[tats] AXUDP".
total frames heard
BPQ keepalives ignored
other non-AXUDP ignored
unsolicited AXUDP ignored
valid AXUDP received
frames sent
frames unsent (resolution failure)
frames unsent (no route)
frames unsent (routing loop)
frames unsent (miscellaneous reasons)
"Total frames heard" includes valid AXUDP plus all other
frames heard on the interface.
"BPQ keepalives" are packets from BPQ systems that are
intended to keep the AXUDP connection alive.
"Other non-AXUDP" is anything else (other than BPQ
keepalives, which is not valid AXUDP, e.g. port
scans, malicious activity etc.
"Unsolicited AXUDP" is valid AXUDP from sources with whom we
don't have a formal arrangement.
"Valid AXUDP received" are the ones accepted into AX25.
"Resolution Failure" occurs when IPLINK has been specified as
a hostname, but that hostname can't be resolved to an
IP address.
"No Route" occurs when there is no IP route which can handle
the encapsulated packet.
"Routing loop" occurs when the IP routing is set up
incorrectly, causing the encapsulated packet to be
encapsulated again ad infinitum.
"Miscellaneous Reasons" usually indicates a temporary IP
routing problem, such as a loose plug.
AXTCP STATS
These are displayed using "S[tats] AXTCP".
total frames heard
frames ignored (too short)
frames ignored (bad header)
frames ignored (bad CRC)
frames received OK
frames sent
frames unsent (not connected)
frames unsent (miscellaneous reasons)
failed / blocked logins
"Total frames heard" includes valid AXTCP plus all other
frames heard on the interface.
"Too short" are received frames too short to be legal AX25.
"Bad header" counts frames where the length specified by the
header didn't match the actual frame length. These
could be malicious, so the connection is dropped for
safety.
"Bad CRC" are received frames long enough to be legitimate
AXTCP, but failed the CRC test.
"Frames received OK" are the ones accepted into AX25.
"Frames sent" are the ones successfully sent.
"Not connected" indicate frames that couldn't be sent because
the TCP link was not connected.
"Miscellaneous reasons" indicates frames that couldn't be sent
due to a temproary problem such as insufficient memory
or a blocked TCP queue.
"Failed / blocked logins" are failed attempts to connect to
the AXTCP server. Usually this results from port
scanning or other malicious activity.
PORT STATS
Displayed by "S[tats] L2" "S[tats] L3" and "S[tats] *".
Note that on a system with more than 7 ports the display may
wrap. This is not ideal, and may be addressed in future
versions.
The PORT stats start with Layer 3 counters, which may also be
displayed in isolation using the "S[tats] L3" command:
Port: 2 4 6 8 9
L3 Frames Heard 0 309 0 0 7
L3 Frames Rcvd 0 137 0 0 7
L3 Frames Sent 0 59 0 0 0
L3 Frames Relayed 0 0 0 0 0
"L3 Frames Heard" is the total number of ax25 level 3 frames
heard, no matter who they are addressed to.
"L3 Frames Rcvd" is the number of ax25 level 3 frames which
were addressed to our XRouter.
"L3 Frames Sent" is the number of ax25 level 3 frames which
originated at our XRouter.
"L3 Frames Relayed" is the number of ax25 level 3 frames
which were routed through our system from elsewhere.
After the level 3 stats come the ax25 level 2 counters, one
per port. These can also be displayed in isolation using the
"S[tats] L2" command:
Port: 2 4 6 8 9
L2 Frames heard 0 628 0 0 78
L2 Frames rcvd 0 520 0 0 74
L2 Resequenced 0 0 0 0 0
L2 Reassembled 0 0 0 0 0
L2 Info Received 0 0 0 0 0
L2 T1 Timeouts 0 239 0 0 0
L2 Digipeated 0 0 0 0 0
L2 Info Sent 0 208 0 0 3
L2 Info re-sent 0 0 0 0 0
L2 Fragmented 0 0 0 0 0
L2 Frames Sent 12 491 18 13 87
L2 REJ Received 0 0 0 0 0
L2 Rx out of seq 0 0 0 0 0
L2 Frames Corrupt 0 1 0 0 0
L2 FRMRs Sent 0 0 0 0 0
L2 FRMRs Rcvd 0 0 0 0 0
Bytes Rcvd 37032 71809 0 0 1589
Bytes Sent 0 21607 869 1460 1597
Poll Timeouts 0 0 0 0 0
Tx/Rx Active% 0/0 0/0 0/0 1/0 0/0
Tx/Rx Peak% 0/0 0/0 0/0 1/0 0/0
Tx/Rx Mean% 0/0 0/0 0/0 0/0 0/0
.
"L2 Frames heard" is the total number of ax25 level 2 frames
heard, whether addressed to us or not.
"L2 Frames rcvd" is the number of ax25 level 2 frames
received which were addressed to XRouter.
"L2 Resequenced" is the number of ax25 level 2 frames
received out of sequence and subsequently used when
the missing frames arrived.
"L2 Reassembled" is the number of ax25 level 2 frames
successfully reassembled from fragments.
"L2 Info Received" is the number of ax25 level 2 information
bearing frames received, i.e. addressed to XRouter.
"L2 T1 Timeouts" counts the number of times that the ax25
level 2 T1 (frack) timer timed out, causing
transmission of a poll frame.
"L2 Digipeated" is the number of ax25 level 2 frames
digipeated by the port. Note that if digiport isn't
zero they may actually have been retransmitted by
another port, but are recorded on the "receiving"
port only.
"L2 Info Sent" is the total number of ax25 level 2
information frames sent by XRouter.
"L2 Info re-sent" records how many ax25 level 2 information
frames were re-sent due to frame loss. A high figure
here, in proportion to the "info sent" figure,
indicates a problem with the RF link, the L2
settings, or the other end's system (e.g. desense, or
running out of buffers).
"L2 Fragmented" is the number of ax25 level 2 information
frames fragmented to fit the outgoing link.
"L2 Frames Sent" is the total number of ax25 level 2 frames,
of any type, sent by XRouter, i.e. it includes all
info, supervisory, and digipeated frames.
"L2 REJ Received" is the number of ax25 level 2 "reject"
frames received, which indicate that the other end of
the link didn't receive some of our frames. There
are many possible reasons for this, some of which are
mentioned in the next paragraph.
"L2 Rx out of seq" shows how many ax25 level 2 frames were
received out of sequence, and indicates that some
incoming frames are getting lost or corupted. A few
of the possible causes might be: signal too weak,
fading, other signals on channel, natural or man made
interference, desense or key clicks from adjacent
transmitters, poor RX audio response, low received
audio, over-deviation, RF frequency mismatch, badly
aligned RX, TNC hardware problems, synthesised rig
taking too long to stabilise on RX after TX, other
end's synthesised rig taking too long to stabilise on
TX, hum, noise, distortion or disturbances on
modulated audio... the list is endless.
"L2 Frames Corrupt" is the number of frames which were dumped
because they were too short to be legal ax25 level 2
frames, or were in some way invalid. It is sometimes
possible for a KISS TNC, especially if running "open
squelch", to send garbage to the router, or the frame
may be trashed by bit errors on the serial link
between TNC and XRouter, and in either case these
frames are dumped if the error can be detected.
"L2 FRMRs Sent/rcvd" shows how many ax25 level 2 "Frame
Reject" frames were sent by the router, or received
by it, indicating serious protocol errors or
deliberate interference.
"Bytes Sent" and "Bytes Rcvd" simply provide a port by port
breakdown of the total bytes sent/rcvd figure.
"Poll Timeouts" counts the number of times a pollled KISS TNC
was polled with no response being received from it.
A large figure might indicate a crashed, disconnected
or unpowered TNC, or data loss on the serial link.
"Tx/Rx Active%" are running averages of the percentage of
time that the TX is tranmitting and RX is receiving.
High figures would indicate a saturated RF channel.
"Tx/Rx Peak%" are the peak values attained by the above.
"Tx/Rx Mean%" are the long term averages of the TX and RX
activity, i.e. since XRouter was booted.
INTERFACE STATS
Following the PORT stats are the INTERFACE stats, which can
also be displayed in isolation using S[tats] L1":
Interface: 2 4 9
RX Bytes: 2048K 71809 1589
RX Overruns: 0 0 0
RX CRC/Parity: 0 0 0
RX Framing err: 0 0 0
RX Break/Abort: 0 0 0
RX Overflow: 0 0 0
RX Misc. errors: 0 0 0
RX Read errors: 0 0 0
TX Bytes: 3463 0 2466
TX Overflows: 0 0 0
TX Underruns: 0 0 0
TX Write errors: 0 0 0
"RX Overruns" counts the number of times a byte was received
before the previous one was read by the CPU. A high
number indicates that the PC is too slow for the
serial port or HDLC card data rate. A 16550-based
serial card may help if the port doesn't already use
one. Failing that, you will have to reduce the baud
rate.
"TX Underruns" is used only by HDLC cards, and counts the
number of times the TX went empty while waiting for
another frame byte to be loaded. A significant
figure indicates the computer is too slow for the
baud rate. Each underrun causes an aborted frame.
"CRC/Framing Errors" counts either the number of bytes
received without proper stop bits (ASYNC interfaces),
or the number of received frames which are corrupt
(HDLC cards). For ASYNC interfaces, a significant
count here can indicate a hardware problem, such as a
faulty line driver, serious RS232 line noise or
distortion, or significant baud rate mismatch. For
HDLC cards it indicates a level 1 problem, such as
distortion in the TX/RX RF or audio paths, or simply
a lot of packet collisions.
"Break/Abort Errors" counts the number of times a line
"space" condition longer than 1 word interval was
received. For serial ports this can indicate a
faulty line driver, a faulty diode matrix on a
multi-drop kiss system, or even (as happened to me)
a malfunctioning TNC EPROM. On HDLC cards it can
result from insufficient audio drive from the RX, a
mismatched baud rate, squelch tails, or genuine ABORT
sequences transmitted by the other end of the link.
"CRC Errors" shows the number of frames abandoned due to CRC
(Cyclic Redundancy Check) or checksum error. For
KISS interfaces this is only maintained if the
CHECKSUM kissoption is enabled.
"Rx Overflow err" shows the number of times a frame was
abandoned because it was too large to fit into the
receive buffer.
"Tx Overflow err" counts the number of times that the TX
couldn't accept a character (serial devices) or a
frame (block devices) because the TX buffer was full.
If you persistently get a high value, it indicates
that the device is too slow for the data throughput.
"RX Misc. errors" counts all sorts of miscellaneous errors,
and the meaning is different for each type of
interface. For example, on KISS interfaces it counts
KISS framing errors.
IDS STATS
Finally "S[tats] IDS", which is sysop-only, elicits a summary
of XRouter's IDS (Intrusion Detection System) stats, which
may look something like this:
IDS Events: 25778 Cmd Overflow: 0
FTP DIR Hacks: 0 IP Addr Heard: 100
IP Addr Banned: 200 IP Banned Total: 183
IP Dgram Blocked: 2076 ICMP Frm Blocked: 32
Honeypot Hits: 0 UDP Segs Ignored: 3251968
UDP Segs Blocked: 22 TCP Segs Ignored: 9967
TCP Segs Blocked: 2022 TCP Conn Blocked: 763
Bogus SYNs: 15776 Smurf Attacks: 0
Fraggle Attacks: 0 IP Frag Attacks: 0
(Tiny=0 Huge=0 Overlapped=0)
TCP Scans: SYN=1 FIN=0 ACK=57 NUL=0 MAI=82 XMS=0 OTH=9600
Rejected Logins: 763 (Telnet=763, Rlogin=0, FTP=0,
TelProxy=0)
Malicious Logins: 182 (Telnet=182, Rlogin=0, FTP=0,
TelProxy=0)
HTTP No-Request: 0 HTTP Bad Request: 0
HTTP Blocked: 0
"IDS Events" is the total number of times the IDS has noticed
something suspicious.
"Cmd Overflow" is the number of times that someone has
attempted a buffer overflow attack.
"FTP DIR Hacks" is the number of attempts to escape from the
FTP root directory.
"IP Addr Heard" is the number of unique IP addresses heard.
"IP Addr Banned" is the number of IP addresses in the "banned
IP" table. As the table is saved across reboots, it
is normal for it to be full.
"IP Banned Total" is the number of new IP addresses banned
since bootup. This figure may exceed the table size
because new bans replace stale ones.
"IP Dgram Blocked" is the number of IP datagrams blocked
because the sender's IP address was in the banned IP
table.
"ICMP Frm Blocked" is the number of ICMP frames blocked
because the sender's IP address was in the banned IP
table.
"Honeypot Hits" is the number of times someone attempted to
access one of the "honeypot" ports. These are traps
which lure port scanners into an IP ban.
"UDP Segs Ignored" is the number of UDP segments ignored
because there was no matching socket to receive them.
"UDP Segs Blocked" is the number of UDP segments blocked
because the sender's IP address was on the banned IP
list.
"TCP Segs Ignored" is the number of TP segments ignored
because there was no matching listener socket.
"TCP Conn Blocked" is the number of TCP connection attempts
blocked because the sender was on the banned IP list.
"Bogus SYNs" is the number of TCP connection attempts blocked
because the SYN was malformed or maliciously crafted.
"Smurf Attacks" are distributed denial of service attacks
which use ICMP directed at broadcast addresses.
"Fraggle Attacks" are variations of Smurf attacks, where the
attacker sends lots of traffic to UDP ports 7 (Echo)
and 19 (CHARGEN)
"IP Frag Attacks" is the number of IP fragmentation attacks.
These attacks attempt to overwhelm or crash the IP
fragment reassembly mechanism.
Tiny - First fragment is too short to contain valid
TCP+IP headers, so it could bypass port-number
filtering.
Huge - Fragment exceeds maximum datagram size.
Overlapped - Fragments which overlap but don't align.
"TCP Scans" is the number of TCP port scans detected and
blocked. Totals for each scan type are shown
separately:
SYN - Scanner sends SYN but never completes the 3 way
TCP handshake.
FIN - TCP segments with only the FIN bit
ACK - Only the ACK flag is set
NUL - NULL scan (no flags are set)
MAI - Maimon scan (FIN and ACK flags set)
XMS - Xmas Tree scan (FIN, PSH and URG flags set)
OTH - Other types of scan
"Rejected Logins" are Telnet / FTP etc logins which were
rejected because the login credentials were incorect.
"Malicious Logins" are TCP logins attempted using suspicious
credentials.
"HTTP No-Request" is the number of connections to XRouter's
HTTP server which didn't contain an HTTP request.
These are usually the result of port scanning.
"HTTP Bad Request" is the number of malformed or maliciously
crafted HTTP requests. These are usually attempts to
exploit vulnerabilities in certain types of HTTP
server or operating system.
"HTTP Blocked" is the number of HTTP server connections
refused because the sender's IP was in the blocked
IP list.
SEE ALSO
STATS(1) -- Display XRouter Statistics.
STEALTH
STEALTH(9) XROUTER REFERENCE MANUAL 17/10/2023
NAME
STEALTH -- TCP/IP Stealth Mode
DESCRIPTION
The experimental command IP QUIET [n] controls whether or not
ICMP error messages are generated. The command may be used at
the command prompt, in BOOTCMDS.SYS, or (without the "IP") in
IROUTE.SYS.
Hackers use automated software to "probe" the network, looking
for unprotected TCP or UDP services and "back doors" such as
NetBios. When they find such a service, they will usually
exploit known bugs, such as buffer overflow problems, to crash
the machine or gain access to sensitive areas.
XRouter has only a handful of standard TCP / UDP services,
none of which pose much of a security risk if configured
correctly, so the probes are more of a bandwidth-wasting
nuisance than a real threat.
Issuing the command "IP QUIET n", where n is a number between
1 and 255 puts XRouter into "stealth mode", the level of which
depends on the number n, which is the sum of the following
values:
1 Suppress ICMP echo replies.
2 Suppress ICMP "Unknown Protocol" messages
4 Suppress TCP resets
8 Suppress all other ICMP error messages.
A value of 0 disables stealth mode and lets TCP/IP operate
normally.
Suppressing ICMP messages, may reduce the bandwidth wasted
and slow up the rate of probing. But it won't confer any
extra security, and will certainly have a detrimental effect
on normal TCP/IP operations.
ICMP error messages are an integral part of the TCP/IP
protocol, and are used to inform a sender of network problems
such as unroutable frames, unsupported protocols, processing
errors etc. They are also used for diagnostic purposes, by
applications such as "Ping" and "TraceRoute".
Using stealth mode therefore prevents the use of diagnostics
and the detection of network problems, and may under some
conditions make everything run more slowly, or fail completely.
If you suppress ICMP echo replies, your system will not
respond to "pings". This may be temporarily useful if you are
being attacked with echo requests, but you would also be
denying others the use of a valuable network diagnostic tool.
It is considered bad practice among the amateur community to
disable services. It will not *prevent* a pingstorm attack,
but it will halve the traffic by suppressing the replies.
If you suppress ICMP "unknown protocol" messages, it will
reduce the bandwidth wasted by protocol scans, i.e. those in
which the protocol number is incremented with each probe.
"Suppressing TCP resets" prevents the TCP layer from sending a
refusal for connect requests aimed at non-existent TCP
services. The request is simply ignored instead. This may be
useful in slowing up the action of so-called "port scanners".
The "Suppress all ICMP error messages" option is not
recommended. It is provided for experimentation only.
SEE ALSO
IP(1) -- IP configuration commands.
BOOTCMDS.SYS(8) -- Commands to Run at Bootup.
IPROUTE.SYS(8) -- IP Routing File.
SYNCACHE
SYNCACHE(9) XROUTER REFERENCE MANUAL 6/9/2023
NAME
SYNCACHE -- TCP SYN Cache.
DESCRIPTION
To combat the ever-growing problem of TCP port scanning,
which wastes TCP resources, XRouter includes a "SYN cache".
In "normal" RFC793 TCP, a received SYN elicits a SYN|ACK,
and the TCP state machine allocates resources then moves to
the SYN_RECEIVED state, awaiting an ACK from the caller.
The nastier port scans tend to send a SYN, wait for the ACK,
then move on without sending a reset. This leaves dozens of
half-open connections, which eventually prevent new
connections from being formed.
With a SYN cache, a received SYN elicits a SYN|ACK as before,
but no resources are allocated. The SYN is cached for a short
while. If an ACK is received for our reply, a normal
connection is created, otherwise the SYN is discarded. This
makes the TCP stack far more resistant to port scans.
The TCP CACHE command is used to display and adjust settings.
SEE ALSO
TCP(1) -- TCP Status / Configuration Commands
TDR
TDR(9) XROUTER REFERENCE MANUAL 21/10/2023
NAME
TDR -- Time Dependent Routing.
DESCRIPTION
Conventional NetRom makes routing decisions based on a fairly
arbitrary metric, i.e. the "route quality", which is assigned
by sysops, and disseminated in nodes broadcasts. There is no
standard for assigning quality, and not only will each sysop
have a different notion of the quality of his links relative
to others, but he will probably wrongly assign the qualities
of those links relative to each other. This leads to
inconsistency and distorted routing.
XRouter includes two systems which attempt to alleviate this
problem, namely Automatic Quality Measurement" (Autoqual)
and "Time Domain Routing" (TDR). Both systems rely on a
slightly different understanding of the "goodness" of a link.
In the better-managed parts of the NetRom network, route
qualities tend to be assigned according to the baud rate of
the link, with adjustments for retry rates, duplex / simplex
and shared channels (in the worst-managed parts, route
qualities are simply assigned to 192 regardless of how good
or bad the link is). The quality is fixed at a compromise
value.
But the actual "goodness" of a link may continually change
with atmospheric conditions, data throughput, other channel
activity, QRM etc. At certain times of day for example, it
may be better to use an alternative link.
A more accurate notion of "goodness" is simply the "Round
Trip Time" (RTT) for the link, i.e. the time taken to send a
packet and get a reply. After all, this is what *really*
matters to users. A link which responds quickly (i.e. with a
low RTT) is perceived by users to be better than a link which
responds slowly. The RTT will track changes in retry rate,
channel loading etc.
The RTT can be easily and consistently measured by software
on a continuous basis, thus the "quality" of the link is
accurately known at all times, and all routers of the same
type will give comparable values independently of the sysop's
notions of quality.
XRouter continually measures RTT and uses it to calculate
a notional "route quality". This quality is displayed by the
"R Q" command, and can either be used as a guide to allow the
sysop to fix the RQ at a sensible value, or XRouter can use
it dynamically, by setting the route to use Autoqual.
(Autoqual is engaged by setting an RQ between 256 and 511).
This RTT to quality conversion is tailored to the British
notion of quality, which gives somewhat lower but more
meaningful qualities.
Autoqual is merely a tool to help sysops set consistent and
meaningful route qualities. The qualities are still under
sysop control, thus open to distortion.
However, by simply broadcasting RTT values instead of
qualities, the influence of the sysop is removed, and a
network based on indisputable *times* rather than arbitrary
*quality* can be created. This is a network which has its
routing metric in the time domain, hence the name "Time
Domain Routing". It may to some extent overlap the
quality-domain network, but the boundaries may be different,
and the two schemes are not compatible. Consider them to be
different dimensions, at 90 degrees to each other.
XRouter implements both time-domain and quality-domain
routing schemes, and will consider information from both
domains when making routing decisions. The same node table
is used for both schemes, since only the metric is different.
In some cases a node may have both quality and time metrics.
As sysop, you have several tools at your disposal for
controlling the size and balance of the two domains. For the
quality domain you have QUALITY which defines the "goodness"
of the links to your neighbours and the "de-rating" of the
qualities which they send to you, MINQUAL, which determines
which nodes get into the nodes table and which are excluded,
MINTXQUAL, which determines how much information you send to
your neighbour nodes, and MAXNODES which determines the
maximum number of nodes visible to you.
For the time domain, you have MAXTT, which defines the
furthest node in "Trip Time" (i.e. RTT/2) terms, MAXHOPS
which defines the furthest node as a function of the number
of intervening nodes, and MAXNODES as above.
You may adjust these parameters to favour one domain over the
other, to exclude one domain altogether, or to strike a
balance between the number of nodes which exist solely in one
domain or the other.
For example, setting MAXTT or MAXHOPS to 0 will exclude all
time-domain information, and Xrouter will behave as a pure
old-fashioned NetRom router. Or you may set MINQUAL to 255,
excluding all quality-domain information (e.g. if there is a
nearby node distorting the netrom qualities), providing of
course you have neighbours which are cabable of time-domain
routing. Or you may wish to limit the visibility of a subnet
from one port (e.g. to a foreign network) by setting a low
MAXHOPS or MAXTT on that port only. This gives you control
which was not possible by quality alone.
XRouter currently (but see compatibility issues) uses the
INP3 protocol to disseminate time-domain routing information.
Unlike NetRom, which uses unconnected-mode "broadcasts" to
all neighbours simultaneously, INP3 sends data to each
neighbour individually, using connected-mode. Whilst it is
usual to make NetRom nodes broadcasts at 1 hour intervals,
INP3 updates are sent every 10 minutes, with additional
updates whenever changes occur.
The time-domain network thus responds much more rapidly to
changes than NetRom does, but if the network is unreliable
(i.e. frequent outages and variable RTT's), a lot of updates
are generated. Although INP3 updates are more compact than
NetRom nodes broadcasts, some sysops may feel that the amount
of routing information is too much for a poor quality RF link.
If so, you may disable INP3 completely by setting the route
MAXTT to 0, or you can agree a low MAXTT with your neighbour
node, which will reduce the volume of data.
You may notice that nodes which are learned solely via INP3
are all stored with a NetRom quality of 0. This is deliberate,
because these nodes have no presence in the quality domain.
Compatibility issues:
Although this is a router manual, not a treatise on advanced
networking, it must be stressed that time-domain and
quality-domain metrics are incompatible, and information
learned from one domain must *never* be "translated" and
broadcast to the other. XRouter measures, uses and
disseminates both time and quality metrics, but always keeps
them separate.
Unfortunately, *some* software (which shall henceforth be
known as "Brand-X") *does* translate information between the
domains, and you should be aware that this may cause you
problems if they are within the horizon of either domain.
For example, in the diagram below, imagine that an XRouter
node (Xr) measures the trip time (TT) to one of its neighbour
nodes (A) as 1.5 seconds, and the sysop has assigned a Netrom
quality of 180.
180
A ---- Xr ---- Bx
\ /
\ /
C ---- D
XRouter broadcasts both pieces of information to neighbour
node (Bx) which is using "Brand-X" software. That software
ignores the 180 and will instead manufacture a quality of 253
from the trip time, using a totally unsuitable algorithm.
By itself this isn't a problem, until the "Brand-X" node
broadcasts it to node (C) which is NetRom-only. Now the
NetRom node thinks it has a higher quality to (A) via (Bx)
than via (Xr). So packets from (C) to (A) will now take the
longer path. What's worse, (Bx) will tell (Xr) that it knows
a better route to (A), and the network will decend into chaos.
A fully interconnected mesh network is very robust, yet the
"Brand-X" sysops seem remarkably reluctant to implement links
which result in a mesh. Maybe the above explains why!
Another problem occurs when the "Brand-X" software translates
in the other direction, i.e. it takes a NetRom quality, which
is a potentially unreliable piece of information, and
magically turns it into a trip time and hop count. Yet
neither trip time nor hop count can ever be inferred from
quality alone!
The consequence is that a node which exists only in the
untrustworthy quality domain, and may have been beyond our
horizon in that domain, now appears in the more trusted time
domain where it can bypass the NetRom de-rating process. The
information could subsequently pass innocently back into the
Netrom network with a higher "quality" than it would have
if received via a more direct pure netrom route.
HISTORY
Early versions of XRouter used a proprietary protocol to
exchange RTT, hops, IP routing, position and other
information between themselves. It was later decided to
adapt XRouter for INP3 compatibility, believing that it would
be a good idea to interconnect XRouter's time domain scheme
with other types of node.
In hindsight this proved to be a mistake, and it is firmly
believed that, unless the "Brand-X" software authors correct
the errors, XRouter and the Netrom network should not be
connected to any other network which includes "Brand-X"
nodes. Fortunately, those nodes are now in decline, and BPQ
is becoming more prevalent. BPQ32 does (correctly) keep time
and quality domains separate.
SEE ALSO
AUTOQUAL(9) -- Automatic Route Quality.
INP3(9) -- Inter-Node Protocol 3
MINQUAL(1) -- Minimum Quality.
MINTXQUAL(1) -- Minimum Quality to Transmit.
ROUTES(1) -- Add, Drop and List Routes.
QUALITY(1) -- NetRom Route Quality.
TELPROXY
TELPROXY(9) XROUTER REFERENCE MANUAL 27/9/2023
NAME
TELPROXY -- Telnet Proxy Server.
DESCRIPTION
The need may arise for a TCP/IP host on the LAN to connect
first to XRouter, before making an ongoing connection from
Xrouter to a target host. Using normal telnet port 23 for
this purpose is not always successful, especially if the
link is required to carry binary data, due to the internal
end-of-line translations and Telnet command sequences which
are part of the Telnet protocol.
The Telnet proxy on TCP port 2323 provides a solution to
this problem, allowing 100% binary connections not only to
TCP/IP targets, but also to Netrom and AX25 targets. This
would typically be used by a TCP/IP-only BBS to perform
FBB compressed forwarding with netrom and ax25 targets.
Upon connection to port 2323, the caller may, or otherwise,
be required to answer a security challenge, according to the
security criteria specified in ACCESS.SYS. The options are:
no challenge, callsign only, or callsign plus password, and
all of these can be made dependent on the caller's IP source
address.
If a password is required, it should be located in file
USERPASS.SYS.
After gaining entry, the user is presented with a short text
explaining the syntax for the outgoing connection, followed
by a short prompt ">". This text is read from file
TELPROXY.MSG, so you may adjust it to your requirements.
The user may now issue a telnet, netrom or ax25 downlink
connect command. XRouter will respond with "Trying ...".
If the downlink is successfully made, connection is reported,
then the stream becomes pure binary for the remainder of the
session.
If the downlink fails to connect, an error message is sent
before the uplink is terminated.
FILES
ACCESS.SYS controls the access requirements for the server.
TELPROXY.MSG provides an optional alternative login message.
TELPROXY.ACL controls which targets can be connected to.
USERPASS.SYS contains the user passwords, if required.
If required, these files must reside in the same directory
as the XRouter executable.
SEE ALSO
ACCESS.SYS(8) -- Telnet Access Control File.
TELPROXY.ACL(8) -- Telnet Proxy Egress Control File.
TELPROXY.MSG(8) -- Telnet Proxy Logon Message File
TELPROXYPORT(7) -- TCP Port for Telnet Proxy.
USERPASS.SYS(8) -- User Passwords File.
TNC2
TNC2(9) XROUTER REFERENCE MANUAL 28/9/2023
NAME
TNC2 -- TNC2 Emulator.
DESCRIPTION
The TNC2 Emulator is a feature which allows RS232 devices
such as weather stations, dumb terminals, GPS and telemetry
devices to send and receive packets as if they were connected
to a real TNC2.
\|/ .---------.
| .-----. | | .-----.
'---| Rig |---| XRouter |----<----| GPS |
'-----' | | RS232 '-----'
'---------'
For example, imagine you have a weather station which is
designed to be connected to a TNC via an RS232 cable. Now
imagine that you already have an APRS port on your XRouter.
How would you get your weather station on air?
You *could* use an additional TNC, radio and antenna, but that
would be a pointless duplication of equipment. Far better to
configure XRouter to emulate a TNC, so that it can interface
directly to the weather station. This allows the weather
station to send to, and receive from, the existing APRS port.
Or you may have a dumb terminal connected to XRouter via an
RS232 cable, and use it to monitor any port, make connections
with other stations etc. This is completely independent of
XRouter's command interface, and does not require a session
with the node.
There are several applications which have TNC2 as one of the
interface options. You may interface them to any of XRouter's
radio ports via that means.
Or perhaps you wish to monitor a radio channel with a data
logging program, or send the channel activity to a serial
printer? The possibilities are limited by your imagination.
Configuration
~~~~~~~~~~~~~
The emulator requires only an INTERFACE in XROUTER.CFG. It
does *not* require a PORT. It is usually configured by
defining an INTERFACE with TYPE=ASYNC and PROTOCOL=TNC2.
Choose SPEED to suit the peripherals, and MTU=256.
Example:
INTERFACE=5
TYPE=ASYNC
COM=1
SPEED=19200
PROTOCOL=TNC2
MTU=256
ENDINTERFACE
You can have as many TNC emulators as you wish, providing you
have an RS232 port for each one. You should preferably use a
different MYCALL or SSID for each one if there is any chance
of more than one TNC being used on the same radio port.
In addition to TYPE=ASYNC, You may also use the TNC2 protocol
over a TYPE=UDP or TYPE=TCP interface.
Operation
~~~~~~~~~
Standard TNC2 commands currently recognised are Ctrl-C,
AUTOLF, CONNECT, CONVERSE, DISCONNECT, DISPLAY, ECHO, FLOW,
HELP, HEADERLN, KONVERSE, MALL, MCOM, MCON, MONITOR, MRPT,
MSTAMP, MYCALL, PORT, PORTS and UNPROTO. Other commands may
be implemented upon request.
You may set the TNC's callsign (using MYCALL) completely
independently of XRouter's callsign, and may select any of
XRouter's radio ports using the PORT command. When you select
a port, the TNC2 emulator receives from, and transmits to,
the radio equipment connected to that port.
All settings are saved to the file TNCn.CFG where 'n' is the
interface number. This file is automatically created if it
doesn't already exist. It is read when XRouter starts up,
so the TNC always returns to its previous configuration. The
file contains binary data, so you must not attempt to edit it.
NOTES
The emulator does not currently accept incoming connections.
That facility may be added upon request.
SEE ALSO
TCP-IFACE(6) -- Interface type TCP.
UDP-IFACE(6) -- Interface type UDP.
WA8DED(9) -- WA8DED TNC Emulator
XROUTER.CFG(8) -- Main Configuraion File
TTYLINK
TTYLINK(9) XROUTER REFERENCE MANUAL 27/9/2023
NAME
TTYLINK -- Keyboard To Keyboard Chat.
DESCRIPTION
TTYLINK is private real-time keyboard-to-keyboard chat
between sysops, which doesn't involve the CHAT server.
The TTYLINK server listens for incoming connections on TCP
port 87 (see TTYLINKPORT) and NetRomX service 87.
Client sessions are initiated by:
(a) telnetting to TCP port 87 on the target system,
or (b) using "TT[ylink] <target_ip>",
or (c) using "C <nodecall | nodealias> 87"
or (d) using "TALK <nodecall | nodealias>"
or (e) using "NTTY <nodecall | nodealias>"
(Options (c) (d) and (e) require that the target is a
reachable NetRomX node)
Upon receiving a connection from a client, the server "pages"
the sysop, who has 90 seconds to respond. The paging consists
of a pop-up dialog on top of the sysop's current window, and
an audible sound (Note: unless AUDIODEVICE is defined, the
sound only works on older-style PC's which have an internal
loudsqueaker). The server also sends this to the client:
TTYLINK at MOBILE:G8PZT-1
Calling sysop for 90 seconds..
Type 'M' at any time to leave a short message,
or 'Q' to quit...
At any point during or after the 90 seconds, the client has
the option to leave a short one-line message (160 chars max)
or to abort the call.
Here's an example where the sysop responded:
*** G8PZT-1 has come online to talk ***
Hello, why are you calling me?
Because I want to, silly!
Fair enough, it's mad talking to oneself you know...
I know, but no-one else is around.
Ok, bye for now
*** The other end terminated the chat
If the sysop takes more than 90 seconds to respond, and the
client has not disconnected, the sysop can still use the
TALK command to initiate a chat with the caller.
Here's an where the sysop didn't respond. Although not
strictly TTYlink, it is a useful compromise, rather than
allow an important call to be missed:
TTYLINK at MOBILE:G8PZT-1
Calling sysop for 90 seconds..
Type 'M' at any time to leave a short message,
or 'Q' to quit...
No response, please type a short (1 line) message now...
(or enter a blank line to skip this step)
Can you call me back to discuss xrpi release asap?
Message saved for sysop
Goodbye
The message is stored in the sysop's PMS, and a flashing
asterisk on the top left corner of the status bar alerts the
sysop to its presence. The sysop can then access their PMS
to read the message like this:
CMD(B/H/K/L/R/S/?)>
l
Msg# Stat Rcvd Time To From Subject
6 PR 22/05 03:25 SYSOP G8PZT TTYLink msg from
G8PZT@VK2DOT-1
CMD(B/H/K/L/R/S/?)>
r 6
Msg#: 6
Rcvd: 22/05 03:25
From: G8PZT
To: SYSOP
Subj: TTYLink msg from G8PZT@VK2DOT-1
Can you call me back to discuss XRPi release asap?
CMD(B/H/K/L/R/S/?)>
It's all a bit untidy at present, but will hopefully be
tidied up in future revisons.
SEE ALSO
NTTY(1) -- Netrom TTYLink.
TALK(1) -- Talk to a user or another sysop.
TTYLINK(1) -- Keyboard chat with another TCP/IP system.
TTYLINKPORT(7) -- TCP Port for TTYLINK Server.
AUDIO(9) -- Audio Output.
SERVICES(9) -- NetRomX Standard Services.
WA8DED
WA8DED(9) XROUTER REFERENCE MANUAL 19/10/2023
NAME
WA8DED -- WA8DED TNC Emulator.
DESCRIPTION
XRouter can emulate a WA8DED TNC, in both normal mode and
"host" mode. Host mode operation is covered in the MAN page
for DEDHOST. Normal mode might be used by a human user, or
by an application designed to work with a WA8DED TNC in this
mode.
.---------. .-----------.
| XRouter |------RS232-------| HyperTerm |<--User
'---------' '-----------'
The user may be located on the same machine as XRouter,
connected to it either via a pair of "virtual" COM ports, or
via a pair of "real" COM ports interconnected with a null
modem cable.
Alternatively, the user may be located on a seperate machine,
using an RS232 null-modem cable to interconnect the machines.
Configuring WA8DED Emulation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The configuration for non-hostmode operation is essentially
the same as for hostmode, except that an APPL block is not
required in XROUTER.CFG. In fact, an interface set up for
hostmode will work OK in non-hostmode too.
1) Decide how to interconnect the user and XRouter.
You can use either a pair of real COM ports and a
null-modem cable, or a virtual com port driver such as
Com0Com.
If using the latter, install it on the PC (if it isn't
already installed) and note the numbers of the two COM
ports it provides. You may need to adjust one or both of
them to a convenient number for your application. Ensure
that "Baud Rate Emulation" and "Enable Buffer Overrun" are
checked on both sides.
2) Add an INTERFACE.
In XROUTER.CFG specify an interface similar to this, where
"x" represents the interface number...
INTERFACE=x
TYPE=ASYNC
COM=18
PROTOCOL=DEDHOST
CHANNELS=4
SPEED=9600
FLOW=0
MTU=256
ENDINTERFACE
COM is the number of one of the real or virtual COM ports
used to connect with the application. XRouter can use COM
numbers up to COM32. On Linux, COM is a TTY device name.
CHANNELS specifies the max no. of host channels the
interface will provide (between 1 and 32). The total
number of host channels available to be shared between all
applications is 64. If XRouter cannot allocate the
requested number of channels it will fail to start. (In
versions up to 200e the number of channels was specified
by INTNUM. This is now deprecated.)
MTU must be 256
SPEED is the serial baud rate.
FLOW must always be set to 0.
- Don't use CHANNEL, IOADDR, or INTNUM keywords.
- Don't try to attach any PORTs to this interface, as they
are not required.
Using WA8DED TNC Emulation in Terminal Mode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
XRouter's WA8DED emulator starts up in "terminal" mode (i.e.
not host mode) and may be therefore tested or used in this
mode using Hyperterm or any other dumb terminal. Wherever
possible, the emulator behaves the same as a "real" WA8DED
TNC, as detailed below:
In normal mode, commands and information are sent from the
terminal to the emulator in the form of lines. Lines may be
up to 256 characters long, including the terminating CARRIAGE
RETURN. If the 256th character entered is not a CARRIAGE
RETURN, it will be discarded and a BELL character will be
output to the terminal. BACKSPACE and DELETE may be used to
remove single characters from the line. The entire line may
be permanently backspaced out by entering a CONTROL-U or
CONTROL-X.
Lines which begin with an ESCAPE character (echoed as '* ')
are interpreted as commands. Lines without a leading ESCAPE
character are sent as information.
Most commands consist of a single letter. Some commands have
an optional parameter. The number of spaces (if any) between
the command and any parameter is not important. If a command
is issued with no parameter, the current value of that
command's parameter is displayed. Unless a parameter is
returned, commands don't normally return any acknowledgement.
By default, XRouter's WA8DED emulator provides the operator
with five virtual TNC channels, numbered 0 to 4 (The actual
number may be altered between 1 and 32 using the CHANNELS=
keyword in the supporting INTERFACE). The terminal is
logically attached to only one of these channels at a time,
selected by the 'S' command.
Channel 0 is reserved for unproto transmissions and
monitoring. This channel does not support connections.
Information sent on channel 0 is always unproto. The unproto
path may be set by issuing a 'C' command when channel 0 is
selected.
Channels other than 0 support connections, but are unproto if
they are not currently connected. Outgoing connect requests
may be issued on any unconnected channel (other than channel
0), while incoming connect requests will use the first
available channel (provided the maximum number of connections
set by the 'Y' command will not be exceeded).
Information received on a connected channel that is not
currently selected will remain queued there until that
channel is selected. The 'L' command may be used to
determine the channel(s) where stored information is located.
Information for transmission is sent only to the currently
selected channel. When a connection is ended, received
information will remain queued until it has been displayed.
Frame monitoring is controlled by the 'M' command. The
command parameter determines the types of frames monitored,
and is a list of desired frames chosen from the letters in
the following table:
LTR FRAME
--- -----
N None
I I frames
U UI frames
S Supervisory frames
C Monitor while connected
+ Call signs to be included (maximum of 8)
- Call signs to be excluded (maximum of 8)
The '+' and '-' parameters may not be used together. If
either is used, it must be the last parameter (followed by
one to eight callsigns, if applicable). If no list of
callsigns is specified to be included or excluded, all
callsigns will be candidates for monitoring. Entering a '+'
or '-' with no callsigns clears the list.
An asterisk displayed after a callsign in the digipeater list
indicates the frame was transmitted by that station. The
control field displayed will be one of the following:
NAME DESCRIPTION
---- -----------
RRa - Receive Ready
RNRa - Receive Not Ready
REJa - Reject
UI - Unnumbered Information
DM - Disconnected Mode
SABM - Connect Request
DISC - Disconnect Request
UA - Unnumbered Acknowledge
FRMR - Frame Reject
Iab - Information
?ccH - Unknown
a = Next expected frame number (0 - 7)
b = Frame number of this frame (0 - 7)
cc = Hexadecimal value
In addition, one of the following characters will be
displayed, reflecting the protocol version, command/response
bits, and the poll/final bit:
(blank) = version 1 frame without poll/final bit
! = version 1 frame with poll/final bit
^ = version 2 command frame without poll bit
+ = version 2 command frame with poll bit
- = version 2 response frame with final bit
v = version 2 response frame without final bit
The protocol identifier field is displayed in hexadecimal
An unattended mode, controlled by the 'U' command, provides
for sending user supplied text to a connecting station, and
then allows that station to leave a brief message. This mode
can operate on all channels simultaneously, but in no way
limits the operator's ability to interact with one of the
connected channels or the ability to make outgoing connect
requests.
When unattended mode is enabled, link status messages are
queued to the associated channel and not output to the
terminal unless that channel is currently selected. Link
status messages will therefore be displayed in chronological
order with the information from that channel.
In addition, text supplied by the user with the 'U' command
will be sent to any station that connects. If channel 0 is
left selected, stations may then connect and leave messages
on channels 1 - 4 (limited by the 'Y' parameter, of course).
The 'L' command may be used to determine if messages have
been left on any channel. Selecting a channel containing
messages will cause all link status and information from that
channel to be displayed. If xon/xoff handshaking is enabled,
CONTROL-S and CONTROL-Q may be used to regulate the output to
the terminal to allow comfortable reading.
Command Summary
~~~~~~~~~~~~~~~
(In terminal mode all commands are preceded by ESC character)
COMMAND PARAMETER DESCRIPTION
------- --------- -----------
A (1) 0 Auto linefeed disabled
1 Auto linefeed enabled
* C Cs1 [Cs2 ... Cs9] Connect path (0=unproto path)
* D Disconnect
E (1) 0 Echo input disabled
1 Echo input enabled
* I Cs Tnc source callsign
JHOST (0) 0 Terminal mode enabled
1 Host mode enabled
K (0) 0 Timestamp disabled
1 Timestamp status messages
2 Timestamp monitoring & status
L [0-n] Display channel status
M (IU) NIUSC+- Monitor mode
S (0) 0-n Select channel (0=unproto)
U (0) 0 [text] Unattended mode disabled
1 [text] Unattended mode enabled
V (0) Displays the software version
Y (4) 0-n Maximum incoming connections
Z (3) 0 Flow disabled, xon/off disabled
1 Flow enabled, xon/off disabled
2 Flow disabled, xon/off enabled
3 Flow enabled, xon/off enabled
(0) Default values are shown in parentheses
n Number of channels, as specified by CHANNELS keyword
* These commands are applicable to each connection channel
Command Description
~~~~~~~~~~~~~~~~~~~
The 'A' (AutoLF) command is used to enable or disable the
automatic insertion of LINEFEED characters after CARRIAGE
RETURN characters to the terminal.
The 'C' (Connect) command is used on channels other than 0 to
initiate a link connection. A 'C' command issued when channel
0 is selected sets the unproto path. If digipeaters are
specified, 'v' or 'via' is not required (but is allowed)
between the destination callsign and the digipeater callsigns,
and callsigns must be seperated by spaces. Note that on
channels > 0 this command ignores the destination path and
only allows connect to the node. The default unproto address
for channel 0 is "CQ".
The 'D' (Disconnect) command is used to initiate a link
disconnection. If there is unsent or unacknowledged
information remaining, the disconnect request frame will not
be sent until all information has been transmitted and
acknowledged. No additional information will be received after
the 'D' command has been issued. A second 'D' command may be
entered to force the transmission of the disconnect request
frame before all information has been sent and acknowledged.
A 'D' command issued during the establishment of a link or
after a disconnect request frame has been transmitted will
cause an immediate return to the disconnected state.
The 'E' (Echo) command is used to enable or disable the
echoing of input (commands and information) to the terminal.
The 'I' (Ident) command is used to set and display the TNC
source callsign. The initial value is the APPLCALL. If no
APPLblock was defined, the initial value is all blanks.
Changing the TNC source callsign on a connected channel is not
permitted. If the TNC source callsign is left blank, the TNC
will not allow connect commands or unproto transmissions. The
callsign stored in channel 0 is used to initialize each
connection channel upon power up or disconnection.
The 'JHOST' command is used to switch between terminal and
host modes. See the DEDHOST MAN page for details of host
mode operation.
The 'K' command controls the time stamping of status messages
and monitored frames.
The 'L' (LinkStatus) command is used to display the link
status of one or all channels. Information displayed
includes the connection path and the number of received frames
not yet displayed, number of send frames not yet transmitted,
number of transmitted frames not yet acknowledged, and the
current retry count. A '+' character preceeding the channel
number indicates the currently selected channel. Operation of
this command when host mode is enabled is somewhat different,
and is described in the MAN page for DEDHOST.
The 'M' (Monitor) command is used to set the frame monitoring
mode. The command parameter determines the types of frames
monitored, and is a list of desired frames chosen from the
letters in the following table:
LTR FRAME
--- -----
N None
I I frames
U UI frames
S Supervisory frames
C Monitor while connected
+ Call signs to be included (maximum of 8)
- Call signs to be excluded (maximum of 8)
The '+' and '-' parameters may not be used together.
If either is used, it must be the last parameter
(followed by one to eight callsigns, if applicable).
If no list of callsigns is specified to be included or
excluded, all callsigns will be candidates for
monitoring. Entering a '+' or '-' with no callsigns
will clear the list.
The 'U' (Unattended) command is used to enable or disable
unattended modes.
The 'V' (Version) command just displays the software version.
In this respect it behaves like TheFirmware instead of WA8DED.
The 'Y' command is used to set the maximum number of
connections that may established by incoming requests. This
command has no effect on the operators ability to initiate
outgoing connection requests.
The 'Z' command is used to enable or disable flow control and
XON/XOFF handshaking to the terminal. If flow control is
enabled, output to the terminal will be inhibited while
entering commands or information. If flow control is
disabled, output to the terminal will not be restricted.
Flow control and xon/xoff handshaking should be disabled
during periods in which the TNC is operated without a
terminal, to avoid suspending output which will consume
buffers. If XON/XOFF handshaking is enabled, terminal
scrolling may be stopped and started using CONTROL-S and
CONTROL-Q characters. Flow control and XON/XOFF handshaking
are not performed when host mode is enabled.
The '@' command is a software maintenance command. A
parameter of 'B' displays the number of free buffers.
SEE ALSO
DEDHOST(9) -- WA8DED Hostmode Emulation.
XROUTER.CFG(8) -- Main Configuration File.
WPAGES
WPAGES(9) XROUTER REFERENCE MANUAL 29/3/2024
COMMAND
WPAGES -- White Pages Database.
DESCRIPTION
The WP (White Pages) database on this mailbox is part of a
world wide distributed database, which holds details of all
recently active Packet users. The database is primarily used
by mailboxes to make mail routing decisions. The data is
also available to users via a number of search commands.
The data is collected from two main sources:
a) from the details a user enters when they register on a
mailbox.
b) from the headers of mail in transit.
There are 3 classes of data as follows:
/U User-entered, via one or more of the "N" commands.
This is the most reliable date.
/I "Is-BBS", generated by each BBS for its own
callsign, and inferred from routing headers, when
the user call and BBS call are the same.
/G "Guessed" or "Gleaned" from routing headers, when
the user call and BBS call are different. Not to
be trusted, because users often send mail from
BBS's that are not their "Home" BBS.
WP data is stored in memory, mirrored in the file WP.DAT,
which is located in the PMS folder. This is a plain text
file, so it can be edited with any text editor if necessary.
The file is read only at boot-up, and is written whenever
there are any changes.
Most mailboxes with WP capability share their data by means
of regular "WP Update" messages. These were supposed to be
sent to "regional" servers, which would collate the data and
send it via regional and national servers to a world server.
That system has fallen apart over time. The current advice
is to send WP updates as private messages to your immediate
neighbours only. This can be set up using one or more
"WpUpdateTo" directives in PMS.CFG.
XRouter only shares "/U" (user-entered) data via WP updates.
If a user has not sent a message, and has not re-registered
on a BBS within a certain period, their details are purged
from the WP database. That period is commonly 90 days, but
can be as little as 30 days. XRouter currently does not
expire WP entries.
There are many packet users who NEVER log into a mailbox,
and who are therefore "invisible" to WP.
The local database can be searched using the I, I@, IC, IH,
IN, IQ and IZ commands, which each have their own MAN pages.
SEE ALSO
INFO(4) -- Display Mailbox or White Pages Information.
PMS.CFG(8) -- PMS Configuration File.
WX
WX(9) XROUTER REFERENCE MANUAL 28/2/2024
NAME
WX(9) -- Weather Information System.
INTRODUCTION
XRouter can gather and store weather information from a local
weather source and/or from the APRS weather broadcasts of up
to 5 neighbour nodes. It can display
the information in response to the WX and INFO commands.
It can also display the information via its HTTP interface,
the NetRomX weather server, the integral MQTT server, and
can broadcast it in APRS-style beacons.
- How it is accessed & presented
- How to set it up
- Wacky ideas
DATA SOURCES
- APRS Weather broadcasts from nearby nodes.
- Files deposited by external WX programs e.g. Cumulus
- MQTT messages addressed to the nodecall.
DATA STORED
For non-local sources, e.g. APRS broadcasts, the following
basic information is stored, if the source provides it:
- Observation date/time
- Callsign of the originating source
- Latitude and longitiude of the observation
- Distance of the observation from XRouter
- Barometric pressure
- Air temperature
- Humidity
- Wind direction
- Wind speed
- Wind gust speed
- Rainfall in last 24 hours
- Rainfall in the last hour
- Rainfall since midnight
For local sources, e.g. import files or MQTT messages, the
following additional data is stored, if the source provides
it:
- Sensor battery state
- Light level
- UV level
If the source provides the required data, the following
"derived" values may also be stored:
- Today's pressure max/min and the times thereof.
- Today's average pressure.
- Today's temperature max.min and the times thereof.
- Today's average temperature
- Tofay's humidity max/min and the times thereof
- Today's average humidity.
- Today's maximum wind and gust speeds and times thereof
- Running average wind direction (last 11 readings)
- Running average wind speed
- Current rainfall rate
- Today's maximum rainfall rate and time threof
- Temperature trend.
- Dew Point
- Wind Chill
- Heat Index
- Wind Run
STORAGE UNITS / PRECISION
Parameter Stored as Precision
--------------------------------------------
Lat/long Degrees 0.01 minutes
Date/time Seconds 1 sec
Pressure Millibars 0.1 mb
Temperature Degrees C 0.1 C
Humidity Percent 1 percent
Wind speed Miles Per Hour 0.1 mph
Wind direction Degrees 1 degree
Rainfall Millimetres 0.1 mm
Wind Run Miles 0.001 mile
Max/Min times Hour:minute 1 minute
Dew point Degrees C 0.1 C
Wind Chill Degrees C 0.1 C
Heat Index Degrees C 0.1 C
STORAGE ACROSS REBOOTS
The WXSAV.DAT file preserves most data across reboots, but
for the first few observations after a reboot there will be
no trend or running average information. That will appear
after a few observations.
DATA ACCESS
COMMAND LINE
The WX command is used to display a list of available WX
datasets, to display the data from a specified source,
or to obtain a WX summary from another XRouter. See the
WX(1) man page for details.
The page displayed by the INFO PAGE command contains a
brief local weather summary comprising date, time, air
pressure, temperature, humidity, wind speed, gust speed,
and wind direction, if such information is available.
WEB PAGE
If XRouter's HTTP server is enabled, and local weather is
available, it is displayed on the following page:
http://{ipaddress[:port]}/localwx
where ipaddress and port are those of XRouter
WX SERVER
XRouter's "weather summary server", accessed via NetromX
service number 16, returns local weather information, if
available. The information is returned in a machine and
human readable plain text form. See the WX-SVC(9) manual
page for more details.
MQTT BROKER
XRouter's integral MQTT broker makes weather information
available, both as "events" and upon request. The former
are published whenever new data arrives, and the latter
are published upon request. The broker may be accessed
either via MQTTPORT on the LAN and/or amprnet, or via a
NetromX connection to service 1883. The inbuilt MQTT
client can be used to make such a connection, as can any
other client of your choosing.
To receive WX "events", subscribe to the following topic:
xrouter/event/{nodecall}/wx/{callsign | #}
To request WX information, first subscribe to
xrouter/status/{nodecall}/wx[callsign]
then PUBlish xrouter/get/{nodecall}/wx[/callsign]
APRS BROADCASTS
XRouter can be configured to broadcast APRS-format WX
beacons at specified intervals on specified PORTs.
MQTT/Json
~~~~~~~~~
Some weather stations supply rainfall in total bucket tips, e.g. “Rainfall”:1186, others as total mm, e.g. “rain_mm” : 467.106.
If “mm” is not prsent
{"time" : "2024-03-04 18:58:15", "model" : "Fineoffset-WH65B", "id" : 80, "battery_ok" : 1, "temperature_C" : 6.200, "humidity" : 89, "wind_dir_deg" : 204, "wind_avg_m_s" : 0.000, "wind_max_m_s" : 0.000, "rain_mm" : 514.096, "uv" : 0, "uvi" : 0, "light_lux" : 0.000, "mic" : "CRC"}
There doesn't seem to be any standard for the field names. For instance the observation timestamp could be sent as “timestamp” or “observed” instead of “time”. Temperature could be sent as “temp”, temperature_deg_c, “temperature_C” and so on.
Xrouter can be customised to recognise the field names used in
the data source, using a set of optional directives in
XROUTER.CFG as follows:
Name Default Purpose
--------------------------------------------------------
WXBATTERY "battery_ok" Sensor battery indication
WXBEARING "wind_deg" Wind direction in degrees
WXGUST "wind_max_m_s" Gust speed in metres per sec
WXHUMID "humidity" Relative humidity in pecent
WXID "id" Sensor number
WXLIGHT "light_lux" Solar Irradiance in lux
WXMODEL "model" Sensor make/model
WXPRESS "pressure" Air pressure in millibars
WXRAIN "rain_mm" Total rainfall in mm
WXSPEED "wind_speed_m_s" Wind speed in metres per sec
WXTEMP "temperature_c" Air temperature in degress C
WXUV "uv" UV level
WXUVINDEX "uvi" UV Index
RELATED DIRECTIVES
WXSENSOR A string of characters (max 31) which identifies
the desired weather sensor in the source data
stream, e.g. "Fineoffset-WH65B".
For use where the data source might contain data
from more than one weather sensor, or from other
types of sensor that may share the same parameter
names, e.g. tyre pressure sensors. There is no
default. If specified, only data whose "model"
field contains the specified string is accepted.
WXSENSORID A string of characters (max 15) which uniquely
identifies a particular sensor among sensors of
the same make/model. e.g. "80".
Can be used in conjunction with WXSENSOR, or on
its own. There is no default. If specified, only
data whose "id" field contains the specified
string is accepted.
WXBUCKET Specifies the "bucket size" in mm for a bucket
tipping pluviometer. This is the amount of rain
required to increment the "rainfall" count by one
unit.
Bucket sizes typically range from 0.1 to 1mm,
with 0.3mm and 0.254mm being common sizes for
amateur weather stations. Defaults to 0.3
WXWINDGAIN A correction factor which can be applied to the
wind speed input to compensate for non-ideal
siting of the anemometer. Default is 1.0.
The "standard height" for wind speed measurements
is 10 metres above unobstructed ground. Due to
air resistance and obstructions, wind speed
reduces at lower heights. If the wind speed at 4m
above ground was half the level at 10 metres, a
WXWINDGAIN of 2 would cause the "correct" wind
speed to be displayed. However, the meaning of
"correct" wind speed is debateable - if a
greenhouse in a sheltered garden can withstand a
wind speed of 49mph before collapsing, it is the
ground level wind speed that's important, not
the 10m AGL speed.
WXWINDGAIN can also be used to adjust
Directives:
~~~~~~~~~~~
WXMODEL - optional. For use where . The field name defaults to “model” is specified by
WXBATTERY:
Optional. Defaults to “battery_ok”
WXBEARING:
Optional. Defaults to “direction”
WXFILE:
Specifies the pathname of a file from which XRouter can read weather data. There is no default. If WXFILE is specified, and the file exists, XRouter reads its contents once per minute. The contents of the file may be in Cumulus WXNOW.TXT or REALTIME.TXT formats, which are well documented on the web.
(list the name value pairs expected here) "Temperature:" Degrees centrigrade "Barometer:" Pressure (millibars) "Wind:" speed in MPH; "Direction:" Degrees; "Gust:" speed in MPH "Humidity:" 0-100 (percent)
WXGUST:
Specifies the field name used for reading the wind gust speed from a JSON message or weather file. Max 15 characters. Defaults to “gust”
WXHUMID:
Specifies the field name used for reading the humidity (in percent) from a JSON message or weather file. Max 15 characters. Defaults to “humidity”.
WXID:
pztncpy (WxId, args, 15); break; case CMD_WXLIGHT: pztncpy (WxLight, args, 15); break; case CMD_WXMODEL: pztncpy (WxModel, args, 15); break; case CMD_WXPRESS: pztncpy (WxPress, args, 15); break; case CMD_WXRAIN: pztncpy (WxRain, args, 15); break; case CMD_WXRAINTYPE: break; case CMD_WXSENSOR: pztncpy (WxSensor, args, 31); break; case CMD_WXSENSORID: pztncpy (WxSensorId, args, 15); break; case CMD_WXSPEED: pztncpy (WxSpeed, args, 15); break; case CMD_WXTEMP: pztncpy (WxTemp, args, 15); break; case CMD_WXTIME: pztncpy (WxTime, args, 15); break; case CMD_WXWINDGAIN: WxWindFactor = atof (args);
WXUVINDEX:
Specifies the JSON field name used for reading the UV index. Defaults to “uvi”.
OPTIONS
UPDATING VIA HTTP
If you have a weather station that can be configured to upload to a custom server using Wunderground PWS protocol, it can upload directly to XRouter.
Configure the weather station as follows:
a) choose "Upload to custom server" b) choose Wunderground protocol c) Set the "Server IP/Hostname:" field to Xrouter's IP d) Set "Path:" to /wx/report? e) Set "station ID:" to a string of your choice, e.g. KidderWX f) Set "Station Key:" to a suitable password of your choice g) Set "Port:" to whatever your HTTPPORT is set to h) Set "Upload Interval" to your choice i) Save
Configure XRouter as follows
# Updates sent as GET requests to /wx/report # Uses Wunderground PWS upload protocol # PWS station ID
WXSENSORID=Fal
# Password
WXCMD=12345
WXWINDGAIN=2.0
API (see REST-WX.9.MAN) and possibly MQTT
a) Retrieve List of Weather Stations:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Request-Type: GET
Request-URL: /api/v1/weather/stations
If successful, the response is an un-named JSON array of
objects, each object containing the following fields:
It is strongly recommended that you use WXSENSOR to avoid reading erroneos data from other type of device.
SEE ALSO
WX(1) -- Display Weather Information.
WXID.7
WXLIGHT.7
WXMODEL.7
WXPRESS.7
WXRAIN.7
WXRAINTYPE.7
WXSENSOR.7
WXSENSORID.7
WXSPEED.7
WXTEMP.7
WXTIME.7
WXWINDGAIN.7
WXUV.7
WX-SVC(9) -- NetRomX Weather Service
XROUTER.CFG(8) -- Main Configuration File.
WX-SVC
WX-SVC(9) XROUTER REFERENCE MANUAL 7/9/2023
NAME
WX-SVC -- NetRomX Weather Service
DESCRIPTION
The weather service returns local weather information, if
available. It is accessed via NetromX service number 16.
The information is returned in machine-readable plain text
form. A typical response would look like this:
Observed: Mon 17 May 2021 06:01:23 +0001
Pressure: 1007.2 mB
Temperature: 11.2 C
Humidity: 67 %
Wind: 23 mph
Direction: 178 deg
Gust: 31 mph
Rain-24h: 24.7 mm
Rain-Today: 19.7 mm
Rain-1h: 3.2 mm
When the client has recieved the information, the server
terminates the connection.
Some fields may be missing if there is no information in them.
The information is derived from received APRS broadcasts, or
from the WXNOW or CUMULUS format files generated by home
weather stations or weather applications. The filename is
specifed by the WXFILE directive in XROUTER.CFG.
Once per minute, XRouter checks the file specified by the
WXFILE directive. If the file is present, and the information
therein is more up to date than the previous data, the
contents of the file are imported.
A WXNOW.TXT file only has 2 lines, for example:
Feb 01 2009 12:34
272/010g006t069r010p030P020h61b1050
where: 272 = Wind direction in degrees.
010 = Average wind speed in MPH.
g006 = Gust speed in MPH
t069 = Temperature in degrees Farenheit
r010 = Rainfall in last hour in 0.01 inch.
p030 = Rainfall in last 24H in 0.01 inch.
P020 = Rainfall since midnight in 0.01 inch.
h61 = Humidity in percent.
b1050 = barometric pressure in millibars.
The Cumulus "realtime.txt" file is a text file with a single
line of space separated values. It contains a list of key
values of the sensors and is re-created frequently. After
creation, it can be set to automatically upload to a website
(or to XRouter) via FTP.
An example of the format is as follows (all one line):
18/10/08 16:03:45 8.4 84 5.8 24.2 33.0 261 0.0 1.0 999.7 W 6
mph C mb mm 146.6 +0.1 85.2 588.4 11.6 20.3 57 3.6 -0.7 10.9
12:00 7.8 14:41 37.4 14:38 44.0 14:28 999.8 16:01 998.4 12:06
1.8.2 448 36.0 10.3 10.5 13 0.2 14 260 2.3 3 1 1 NNW 2040 ft
12.3 11.1 420.1 1 13.6
XRouter currently parses the following fields from
realtime.txt:
1 Observation date
2 Observation time
3 Temperature
4 Humidity
6 Wind speed
8 Wind direction
9 Rain rate per hour
10 Rain today
11 Barometric pressure
14 Wind units - m/s, mph, km/h, kts
15 Temperature units - degree C, degree F
16 Pressure units - mb, hPa, in
17 Rainfall units - mm, in
41 Gust speed
48 Rainfall last hour
There is another (non-standard) format that XRouter can import
from a WX file. This consists of "<name>: <value>" pairs as
follows:
Temperature: 22.7
Barometer: 1015
Wind: 6
Direction: 178
Gust: 12
Humidity: 67
The fields can be in any order, and need not all be present.
They may be seperated by spaces or tabs.
At present, temperature must be in Centigrade, pressure in
millibars, and wind speeds in MPH. There are plans to make
this accept other units.
If you don't have a weather station that outputs one of the
above formats, by using suitable software or scripts you could
extract weather information from your WX station and write it
to a file in one of the above 3 formats.
For example, you could use a cheap RTL dongle and "rtl_433"
software on the Pi to receive and decode the 433.9 MHz OOK
transmissions from your weather station to its base unit.
You could even pull weather information for your area off the
web and write it to a file. But that is beyond the scope of
this document.
SEE ALSO
WX(1) -- Display Weather Information.
WXFILE(7) -- Specify Weather Import File.
SERVICES(9) -- NetRomX Standard Services.
YAM
YAM(9) XROUTER REFERENCE MANUAL 29/9/2023
NAME
YAM -- "Yet Another Modem" HDLC Modem.
DESCRIPTION
The "YAM" modem conects to a COM port, and implements the
functions of a TNC in a FPGA (Field Programmable Gate Array).
XRouter includes support for the YAM modem, and the interface
should be defined in XROUTER.CFG as follows:
INTERFACE=10 <- Adjust to suit
TYPE=YAM
COM=1 <- COM port to which YAM is connected
MTU=256
SPEED=1200 <- Radio speed (not serial comms speed!)
PROTOCOL=HDLC <- Only HDLC supported at present
ENDINTERFACE
SPEED is the *radio* baud rate and should match the modem's
configuration, otherwise TXDELAY and TXTAIL timings will be
wrong. You can omit SPEED and define RFBAUDS in the port
instead. Communication between between XRouter and YAM via
the RS232 cable always takes place at 19200 bauds.
PROTOCOL *must* be HDLC. No other protocols are supported at
present.
Each YAM interface supports only one PORT. You must use a
separate INTERFACE and PORT for each YAM board.
Port Settings
~~~~~~~~~~~~~
A typical PORT might be defined as follows:
PORT
ID=YAM 1200 Bauds 144.650MHz
INTERFACENUM=10
CHANNEL=A
SPEED=1200
FULLDUP=0
TXDELAY=150
ENDPORT
CHANNEL is ignored, but must be present. FULLDUP can be used,
as the YAM is capable of full duplex operation, but SOFTDCD is
ignored because it has no meaning for a YAM board.
YAM will INTERLOCK with other YAM interfaces and with all
types of SCC card, but not with KISS TNC's since XRouter has
no knowledge of, or control over when a KISS TNC is
transmitting.
Notes
~~~~~
The YAM modem uses TXD, RXD, RTS, CTS, DTR, DSR, RI and DCD so
a full 8 wire plus ground cable is required.
Some PC's either don't provide enough DC voltage/current to
supply the YAM board or the RS232 inputs sink too much
current. This is a hardware problem, not an XRouter problem.
It can be overcome by using an external supply to power the
YAM board.
XRouter does not program the FPGA therefore YAM modems must be
initialised by running YAMINIT (supplied with the modem)
before starting XRouter. It is probably best to do this in a
startup batch file. "YAMINIT yam12v11.mcs 1" will program the
YAM for COM1 with 1200 baud RF speed. The YAM is capable of
1200, 2400 or 9600 baud simply by choosing the appropriate
.MCS file.
For further information you must refer to the YAM
manufacturer's documentation.
CAVEATS
YAM has not been tested since the XRouter code was ported from
DOS to Windows. Reports would be welcome.
SEE ALSO
XROUTER.CFG(8) -- Main Configuration File.
packet/xrouter/docs/section9-miscellaneoustopics.txt · Last modified: 2025/04/22 02:33 by m0mzf