
Last modified: 30th December 2023


           Release notes for XRouter version 503
           #####################################


TL;DR XRouter is improved. You may have to modify your XROUTER.CFG

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

Now we've got rid of the people with the attention span of a gnat, here are the notes for people who CAN be bothered to read :-)

*************************************************************************

IMPORTANT:
=========

Your XROUTER.CFG file *must* contain AT LEAST one of the following:

	- LOCATOR
	- LATITUDE and LONGITUDE
	- An APRS-style position string in IDMSG

If you fail to include at least one of the above options, XRouter will refuse to start, and will display the message:

	XROUTER.CFG: ERROR in line xxx - Missing LOCATOR

(See the section "Using LATITUDE and LONGITUDE Directives" below [7])

You may wish to add CONTACT, MAPCOMMENT and FREQUENCY, to improve your presence on the new mapping system.

*************************************************************************

NAMING CONVENTION
=================

XRouter is distributed as three types of executable.

	- "XRPi" is XRouter for Raspberry Pi.
	- "XRLin" is XRouter for x86 Linux.
        - "XRWin" is XRouter for 32-bit Windows.

The companion "remote monitor" program is similarly distributed in three forms:

	- XRPiMon is for Raspberry Pi
	- XRLinMon is for x86 linux
        - XRMon.exe is for 32-bit Windows.

The generic names "XRouter" and "XRMon" are used throughout this document, to avoid duplication.

*************************************************************************

What's New Since 502?
=====================

The answer depends on which sub-version of 502!! Some of you may be running versions as late as 502r, in which case you will already be familiar with some of the changes.

The following are SOME of the changes since the version 502 release notes dated 11th Mar 2022. The numbers in square brackets [] refer to sections later in this document...

* Added remote "consoles" (using XrMon). [1]
* Improved XrMon. [2]
* XrMon may now be used on separate machine(s) to XRouter. [3]
* XRouter now suports BPQ's QTTermTCP terminal. [4]
* Improved HTTP interface (unfinished but functional). [5]
* PMS, CHAT and terminal may now be used via web interface. [5]
* Improved format of position display in Mheard, DX, WX, INFO etc. [6]
* Added LATITUDE and LONGITUDE directives [7].
* Added L4 T3 timer, to detect zombie links. [8]
* Added L4T3 directive. [8]
* Added reporting to a node mapping server. [9]
* Added MAPSERVADDR and MAPSERVPORT directives. [9]
* Added CONTACT and MAPCOMMENT directives. [9]
* Added FREQUENCY [9] HAAT [10] directives.
* Added "MHSIZE" command to resize MHeard tables on the fly. [11]
* Added "MH ALL" command, to show MH lists from all ports. [12]
* Added MHeard server (NetRomX service 26) [13]
* Added DX server (NetRomX service 27) [14]
* Added MH_UNIQUE (8) and MH_PRESERVE options (16) to MHFLAGS [15]
* Added "BCAST <port>" command to force a nodes broadcast. [16]
* Added the ability to run as daemon, using "-d" switch. [17]
* Allowed chat peer links to be dual PZT/RTL mode. [18]
* Improved logging and logging controls. [19][20]
* Added per-port CTEXT and CTFLAGS. [21]
* Added "CTEXT" and "CTFLAGS" commands. [22]
* Added "live" CTEXT option. [23]
* Allowed MON ON to be used in BOOTCMDS.SYS [24]
* Added BOOTWIN directive, to specify initial displayed window. [25]
* Added EXCLUDE command. [26]
* Added INFO PAGE and INFO MORE information pages. [27]
* Added MQTT daemon [28] and broker [29]
* Added "Teletext" display mode. [30]
* Added some Scandic keyboard characters (unfinished). [31]
* Added the means to set TNC's into KISS mode upon startup [39]
* Added alternative way to force L2 connect to neighbour node [40]
* Added / updated HELP pages [42]
* Removed SSID's on usercalls sent to RoundTable chat. [32]
* BugFix: "KISSTCP Connections time out every 5 minutes". [33]
* BugFix: "Polled KISS not working". [34]
* BugFix: "Private Chat Messages stored in wrong directory". [35]
* Improved stats counting.
* MHeard and DX lists are now saved across reboots & every 20 mins.
* Filenames in CHAT subdirectory are now all same case (upper)
* BugFix: "Corrupt L3RTT from 64-bit TheNetNode causes bad Alias".[36]
* BugFix: "XROUTER.CFG 'Locked Routes' section doesn't work". [37]
* BugFix: "Hex values shown by MPORT help panel are wrong" [41]
* BugFix: "DX log filename still used DOS backslashes".
* BugFix: "BPQ's axudp "keepalives" trigger IDS warning and IP ban".
* BugFix: "Segfaults at bootup if port ID is omitted".
* BugFix: "FINGER causes segfault".
* BugFix: "Remote tracing sessions sometimes don't trace"
* BugFix: "On nodes monitor window, F3 does nothing"
* Reinstated chat server's "/recent" command. [38]
* Added: Sysop's blog [44]
* Added: Message wall / Guestbook [45]
* Added: REST interface to BLOG, WALL and PMS. [46]
* Added: Dutch language [48]
* Added: View sysop's manual via HTTP interface [49]
* Added: New command "RH" (read including routing headers) to PMS [50]
* Changed: In PMS, R[ead] no longer displays routing headers. [50]
* Added: 32-bit Windows version. [51]
* Added: tracing for DNS, MDNS, SSDP, NBNS and NBDS [52]
* Prevented IP route learning via INP3 on AXIP/AXUDP connections. [53]
* Added: recursion prevention and error stats to AXIP and AXUDP [54]
* Added: AXIP and AXUDP subcommands to the S[tats] command [55]
* Added recursion prevention and error counts to ip stack [56]
* Added: extra IP stats revealed by "S[tats] IP" [57]
* Updated: MAN files (over 200 new ones added). [58]


*************************************************************************

[1] Remote Consoles
===================

Up till now, only the first 7 of XRouter's "windows" have been usable via XR*mon. Now the "consoles", i.e. windows 8 to 12 can be used too.

These "remote consoles" have exactly the same capabilities as the inbuilt ones, but are fully independent of them. You can trace, capture, scroll back, and do sessions exactly the same as on a regular console.

The number of remote consoles is the same as the number of local ones. i.e. if you specify NUMCONSOLES=3, you will get 3 local and 3 remote consoles.

The remote consoles previously used a console window of 80 colums by 25 rows, which meant that the available viewing area was only 21 rows. They now have an 80x25 viewing area, allowing Teletext pages to be viewed without scrolling.

*************************************************************************

[2] Improved XR*Mon
===================

In order to make best use of the new consoles, you will need version 0.3 of XRPiMon, XRLinMon or XRWinMon.

The older versions will still work, but the F4, F5 and arrow keys were never needed, so they weren't implemented. XR*Mon version 0.3 implements all the control keys needed to operate consoles.

When used in conjunction with XRouter v503, versions 0.3 of XrLinMon and XrWinMon will resize their own terminal windows to fit the display. However THIS DOES NOT WORK ON RASPBERRY PI - you will have to set the terminal window to 80x25 before running XrPiMon 

####
Note: If Xr*Mon appears to "freeze" for several seconds at a time, it is most likely that you have another copy of Xr*Mon monitoring the same XRouter window. At present, each of XRouter's windows only supports ONE copy of Xr*mon at a time
###

*************************************************************************

[3] Remote Monitoring from Other Machines
=========================================

The original XRMon was a "quick and dirty" proof of concept, which allowed several of XRouter's "windows" to be visible at the same time. Until now it used hardwired IP addresses, and would only work on the same machine as XRouter. 

XrMon version 0.3, when used with XRouter v503, can be located on different machines to XRouter itself. This won't work through a firewall however.

*************************************************************************
 
[4] Using QTTermTCP with XRouter
================================

QTTermTCP is a very popular "terminal" program for Packet Radio, written by G8BPQ for use with BPQ node and other Packet programs. It can now be used with XRouter version 502n or later).

STEP 1: Ensure that XRouter has an IPADDRESS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For security reasons, XRouter disables *all* TCP/IP functionality, even on localhost, by default. This restriction is lifted if you give XRouter an IP address, using the global IPADDRESS directive in XROUTER.CFG.

It doesn't matter what IP address you specify here. Any valid dotted quad will do because, unless you have set up an ethernet INTERFACE and PORT, XRouter will always use the Linux kernel stack for local operations.

(If you have a 44-net address, that's a good one to use, because it will allow you to use TCP/IP over radio.)

(See http://ohiopacket.org/xrpi/docs/xrcfg.htm#ipaddress)


STEP 2: Ensure that XRouter has a Suitable TCP Server Port
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

QTTermTCP requires a TCP "port" number to connect to (note this is a TCP "service number" not a PORT on XRouter).
The best option is to use TELPROXYPORT (default=2323) which is designed for non-human interactions. However, you can also use TELNETPORT (default=23) or RLOGINPORT (default=513).

Connections to TELNETPORT receive a more verbose welcome text than those to TELPROXYPORT or RLOGINPORT, but QTTermTCP will happily use any of them.

If you use RLOGINPORT, your session will have full sysop privileges.

If you use TELNETPORT your session will NOT have sysop privileges (you can however escalate privileges using the "@" command.

The "standard" numbers for Telnet and RLogin are 23 and 513 respectively. Linux will not let XRouter open those ports unless XRouter is run from a root account, or is given the "capability" by the following command:

	sudo setcap cap_net_bind_service=pe xrpi

	(substitute xrlin for xrpi if you are on x86)

You can avoid this by setting the port numbers to something above 1024.

	Example: TELNETPORT=6023

(See ohiopacket.org/xrpi/docs/tcp-ports.htm for more info.)

If you have modified XROUTER.CFG, don't forget to save it.


STEP 3: Setup a callsign and PASSWORD in XRouter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Non-guest TCP connections to XRouter require a password.

Sysop passwords reside in PASSWORD.SYS. Ordinary "user" passwords reside in USERPASS.SYS (note that all XRouter configuration filenames are in UPPERCASE to make their purpose obvious).

If you are using RLOGINPORT or the "@" command, XRouter checks PASSWORD.SYS. If you are using TELNETPORT, XRouter checks USERPASS.SYS instead.

The format of entries in both files is the same:

	<callsign> <password>

The callsign must not include an SSID, and neither field can contain spaces. A suitable example would be like this:

	g8pzt thisismypassword

You may set up the same password in both files, but it is good practice to use different ones.

You MUST use a valid callsign, not a username such as "root" or "admin", which will always be rejected.


STEP 4: Allow Incoming Connects to QTTermTCP (OPTIONAL)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Skip this step if you DON'T wish to allow incoming connections.

QTTermTCP can be configured to allow incoming connections (usually on TCP port 8015), but you must also explicitly tell XRouter where to route those connections. This is done using the APPL (Application) directive in XROUTER.CFG.

The simplest form would be:

	# For incoming connections to QTTERMTCP
	APPL=1
		APPLNAME=SYSOP
		APPLTYPE=TCP,8015
	ENDAPPL

The above would create a new command called SYSOP, which if invoked would connect via TCP to localhost port 8015, on which QTermTCP should hopefully be listening. Note that you have to ENABLE this facility in QTTermTCP - see step 9 below. The application number is not important; you could just as easily make it application number 7 if you wished. Likewise the application name doesn't have to be SYSOP.

If you want QTTermTCP to accept DIRECT connections from AX25, you have to specify a destination callsign for those connections. That is done by adding APPLCALL as follows:

	# For incoming connections to QTTERMTCP
	APPL=1
		APPLNAME=SYSOP
		APPLTYPE=TCP,8015
		APPLCALL=G9ZZZ
	ENDAPPL

To accept direct connections from NetRom, you would need to add APPLALIAS and APPLQUAL, but that is NOT recommended for casual use because it would clutter up the nodes tables with transient nodes, which cause excess routing information raffic as they come and go.

If you have modified XROUTER.CFG, don't forget to save it.


STEP 5: Start (or Restart) XRouter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A restart is required only if you have made changes to XROUTER.CFG.


STEP 6: Start QTTermTCP if Not Already Running
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

It should be obvious, but someone will moan if I don't spell it out.


STEP 7: Set Up a Host in QTTermTCP
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Click Setup -> Hosts -> New Host and fill in the hostname or IP address of XRouter. If you are running QTTermTCP on the same machine as XRouter, enter "127.0.0.1" or "localhost" here. If XRouter is on a different machine, enter that machine's hostname or IP address instead.

Under "Port:" enter the service number you chose for TELNETPORT or RLOGINPORT.

Under "User:" and "Password:" enter the callsign and password chosen in step 3.

Click "save" when you are done.


STEP 8: Connect QTTermTCP to XRouter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Click "Connect" and QTTermTCP will present you with a list of hostnames. 

If you have several systems on the same machine they will all rather helpfully be called "localhost", and you will have to invoke voodoo to choose the correct one!

If you select the correct one, you should hopefully be able to connect. If not, the lower screen may give some clue, for instance "bad password!".


STEP 9: Enable Incoming Connections To QTTermTCP
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Ignore this step if you DON'T wish to allow incoming connections.

In QTTermTCP, click on "Listen", check the "Enable listen" box, enter the port number chosen in step 4, and a "conenct text" which is sent to incoming connectees.

Click OK and you're all done.

In "single window" mode, QTTermTCP only allows incoming connections when it is idle, ie when it is not downlinked to XRouter. In "tabbed" or "MDI" modes, this restriction does not apply.

*************************************************************************

[5] Improved HTTP Interface
===========================

The previous HTTP interface was functional but basic. By default it was low bandwidth, so that it could be used across radio links. It was left to sysops to design their own pages and CSS, and some did a very good job. But not all sysops are fluent in HTML/CSS, so many systems were undeveloped.

The existing interface has been retained for backward compatibility, but a second one has been added, with a set of inbuilt pages that require no HTML skills. These pages can be restyled to some extent using CSS, but the fundamental structure can't be altered.

Instead of using Java *applets* for Terminal and CHAT operations, the new pages use Javascript. The web interface also provides access to the  PMS, blog and message wall, plus the sysop's manual.

The new interface is only part finished so far. There's a lot more to be added.

*************************************************************************

[6] Improved Position Displays
==============================

In previous versions, the MHeard, and DX lists, plus NODE, INFO and WX outputs displayed node positions in APRS format, i.e. degrees and decimal minutes, with leading zeroes, e.g. "0940.15N 00215.04W".

This cluttered and complicated format was more suitable for machine-reading than human-reading, and was causing confusion, because cartography these days predominantly uses decimal degrees, with degrees, minutes and seconds as a second choice. Degrees plus decimal minutes is rarely used. So the format has now been changed to decimal minutes, for example "9.6692N  2.2506W".

*************************************************************************

[7] Using LATITUDE and LONGITUDE Directives
===========================================

Specifying XRouter's location on the planet using LOCATOR is easy, as long as you know your 6 or 8 character locator square. The alternative was to set it by including an APRS-format position string at the start of IDMSG. But calculating that string is not easy, as most maps give co-ordinates in either decimal degrees, or degrees minutes and seconds. Neither of these can easily be translated to APRS format.

Therefore XRouter's position can now be specified by LATITUDE and LONGITUDE directives in XROUTER.CFG. The values used with these directives are DECIMAL DEGREES, e.g. "LATITUDE=52.4532". You can supply greater or lesser precision if you wish.

Note that southern latitudes and western longitudes are specified using negative numbers, e.g. "LATITUDE=-53.247", "LONGITUDE=-27.423". You should not append NSEW characters after the numbers.

If LATITUDE and LONGITUDE are supplied, LOCATOR is calculated by XRouter, but if you also specify LOCATOR, it overrides the calculated one.

You can specify position directives in any order, and any place in the config file. The algorithm which calculates positions is not actioned until after all the information is known.

*************************************************************************

[8] L4 Link Check
=================

AX25L2 has a "T3" (Link Check) timer, which periodically tests the link to make sure it is still alive. But NetRom L4 doesn't have an equivalent. Therefore sessions which use L4 circuits require an inactivity timeout so they can release resources if the other end simply disappears without sending a DREQ.

This timeout can be a nuisance, for example on a chat connection which needs to stay open for long periods of time without any interaction from the user. There is the option to send chat "keepalive" frames, but they clutter up the display.

Therefore I have removed the session layer timeout on CHAT, and added a NetRom layer 4 (L4T3) timer. If there is no activity on the L4 circuit for (IDLETIME-60) seconds, an L4INFO frame is sent with an empty payload.

If the link its patent, this frame should elicit an IACK from the other end. If it doesn't, the normal L4T1 timer will cause retries. If the link is dead, it will retry out or receive a RSET.

Although this helps to weed out zombie circuits, it is NOT a keepalive. It will NOT prevent *session layer* inactivity timeouts. 

The link check interval defaults to 840 seconds (14 minutes), but can be changed using the L4T3 directive in XROUTER.CFG. It can be disabled by specifying "L4T3=0".

*************************************************************************

[9] Node Map
============

Until now, XRouters have been absent from most web-based packet network maps. This is about to change.

XRouter now reports its position and various other information to a mapping server. This information will eventually be used, along with information from other types of node, to construct a comprehensive near-real-time network map.

Unfortuately, we are still waiting for the "cartographer" to finish this final step. Maybe with more information being reported, he may be more inspired to work on it.
 
This is emphatically not "spyware". The intention is solely to visualise the packet network, to aid network management, planning and usage. All the data is sent to the server in plain text, so that you can Wireshark it and be satisfied that nothing untoward is going on.

If you are uncomfortable about sharing your node's location, you can supply deliberately vague or even slightly false co-ordinates. A mile or two error in any direction is probably of no consequence to anyone unless you are planning RF links.

I would urge you not to opt-out, but if you *really* prefer your node to be absent from the map, you can set MAPSERVPORT=0 in XROUTER.CFG.

Some other new directives have been added to XROUTER.CFG to support the mapping function, as follows:

New global directive CONTACT can be used (once only) to provide an email address for the system operator, a link to a website, or a real address. For example:

	CONTACT=g9dum@wmpkt.org
	CONTACT=www.wmpkt.org/contacts
	CONTACT=PO Box 43, Dudley,West Midlands

New global directive MAPCOMMENT can be used (once only) to specify a short text which pops up when someone clicks on your node on the map. for example:

	MAPCOMMENT=XRLin (XRouter for x86 Linux) alpha test node
	MAPCOMMENT=Beacon Hill Trunking Only

New global directives MAPSERVADDR and MAPSERVPORT can be used to override the default server address and port, if the server changes in future.

Finally, FREQUENCY is a new directive which can be used in PORT definition blocks. The value should be specified in Hz, e.g.

	FREQUENCY=144800000

Naturally this applies only to RF ports.

The new global directives may be placed anywhere in the config file, and FREQUENCY may be placed anywhere in a PORT definition block.

*************************************************************************

[10] New Global Directive HAAT
==============================

HAAT (Height Above Average Terrain) is a value typically used in APRS reporting. It specifies the antenna height in metres above the averaged terrain height. This allows a rough estimate of the radio range.

At present it is only displayed on the HTML "info" page. It really ought to be per-port, because multi-port systems might have separate antennas at digfferent HAATs.

There is a calculator on the FCC website that allows you to calculate your HAAT. Unless the ground falls away in every direction, it is not uncommon to see *negative* HAAT values, e.g.

	HAAT=-15

meaning that the antenna is 15 metres BELOW the average terrain.

HAAT may be placed anywhere in the config file.

*************************************************************************

[11] New MHSize Command
=======================

This command allows MHeard tables to be resized on the fly, i.e. without having to restart XRouter. It replaces the previous (confusing) command "MH <port> <size>".

	Syntax:		MHS[ize] <port> [slots]

	Examples:	MHS 4        <-- show size of port 4's table
			MHS 4 25     <-- Set port 4's table to 25 slots

If the table is made larger, the existing entries are retained. If it is made smaller, the oldest entries are discarded.

*************************************************************************

[12] MHEARD Command New Option
==============================

As before, MH[eard] by itself lists the ports which have MHeard enabled, whilst "MH <portnum>" shows the MHeard list for <portnum>. But what if you want to see which ports have been active the most recently? On a big node that could be difficult.

The new "MH ALL" command displays a single MHeard list, containing up to 100 entries from all MH-enabled ports, with the most recently heard at the start of the list, for example:

mh all

G8PZT:KIDDER} Heard list for all ports:

Port Callsign  Date  Time  Frames  Via       Type     Position
 10  ZL2AQY-2  19/08 04:41  35531             N   36.7138S 174.7451E
 12  VE2PKT-4  19/08 04:41 259627             N A 46.4326N  72.6276W
  8  K5DAT-5   19/08 04:41 313154             N   
 16  G4GVZ     19/08 04:41     85  WIDE1          51.8943N   2.0871W
 15  GB7NXT    19/08 04:40 127747             N   
  4  VK2DOT-1  19/08 04:40 295095             NI  33.3868S 151.3570E
  7  VA2OM-4   19/08 04:40 274346             N   26.1736N  98.0885W
 11  G7VJA-5   19/08 04:40  79840             N   50.9950N   4.4806W
 14  G1GXB-3   19/08 04:39  38575             N   
  6  GB7COV-11 19/08 04:38 171787             N   
 16  MB7UNE-10 19/08 04:38     40  WIDE2          51.5845N   2.8361W
 16  MB7VV-10  19/08 04:37   1658  M0WOF-1        51.4305N   2.4090W
 16  M0WOF-1   19/08 04:37  10439            D    52.3096N   2.7211W
 16  MB7UB     19/08 04:31     11  WIDE2          51.3795N   2.3271W
 16  MB7UVV-10 19/08 04:31     26  WIDE2          51.4351N   2.5008W
 16  G8PZT     19/08 04:30    696  WIDE1          52.4000N   2.2500W
 14  GB7SOU-1  19/08 04:30   4506             N   
  9  KB8UVN-4  19/08 04:29  40661             N   

*************************************************************************

[13] MHeard Server
==================

This server, which uses NetRomX service number 26, allows someone at one XRouter to view the MHeard lists of another XRouter, using a single command.

The syntax of that command is as follows:

	MH[eard] <nodecall | alias> [portnum | ALL]

For example:

	mh kidder
	G8PZT-1:MOBILE} Trying G8PZT::26...
	G8PZT-1:MOBILE} Connected to G8PZT::26

	G8PZT:KIDDER} MHeard available on the following ports: 2, 4, 5,
	6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16

	G8PZT-1:MOBILE} Welcome back    

	mh kidder 16
	G8PZT-1:MOBILE} Trying G8PZT::26...
	G8PZT-1:MOBILE} Connected to G8PZT::26

	G8PZT:KIDDER} Heard list for port 16:
	(list displayed here)

	G8PZT-1:MOBILE} Welcome back

If <nodecall | alias> is omitted the local MHeard lists are displayed instead.

*************************************************************************

[14] DX Server
==============

This server, which uses NetRomX service number 27, allows someone at one XRouter to view the "DX list" of another XRouter, using a single command.

The syntax of the command is as follows:

	DX <nodecall | alias> [portnum]

For example: "DX KIDDER" displays the all-ports DX list at the KIDDER node, whilst "DX KIDDER 16" displays only KIDDER's port 16.

	dx kidder 16
	G8PZT-1:MOBILE} Trying G8PZT::27...
	G8PZT-1:MOBILE} Connected to G8PZT::27

	G8PZT:KIDDER} Dx list:
	Port Callsign  Dist   Dir Date  Time  Frames Position
	16   YO5ZK-2   5820Km 177 11/07 15:48     40 00.0000N  0.0000E
	16   MB7UG      161Km 146 09/07 09:03      6 51.1890N  0.9698W
	16   MB7VV-10   108Km 186 09/08 09:24     74 51.4305N  2.4090W
	16   M7DBB-7     71Km 235 06/08 14:28      8 52.0240N  3.1026W
	16   MB7VR       68Km  90 18/08 01:46     93 52.3910N  1.2453W
	16   M0TRD-7     66Km 177 11/07 19:12      4 51.8073N  2.1925W
	16   M0KTN       64Km 171 13/08 20:56      1 51.8316N  2.1035W
	16   M0MSN-9     64Km 183 10/08 07:51      1 51.8276N  2.2973W 
	(End of list)

	G8PZT-1:MOBILE} Welcome back

If <nodecall | alias> is omitted the local DX list is displayed instead.

*************************************************************************

[15] New options in MHFLAGS
============================

MH_UNIQUE (decimal 8)
~~~~~~~~~

The MHeard lists normally show ONE entry for each source callsign. If that station was heard via a digipeater, the digipeater callsign is also shown, for example:

Callsign  Date  Time  Frames  Via   Type     Position         Dist Dir
----------------------------------------------------------------------
G4GVZ     29/06 21:30     17  WIDE1  D    5153.66N 00205.23W  57Km 169°

In this particular case G4GVZ can also be heard DIRECT, but that is not obvious from the above. We can't tell now many frames were heard direct, and how many were heard via WIDE1.

The new MH_UNIQUE option in MHFLAGS allows the direct and digipeated cases to be recorded separately, for example:  

Callsign  Date  Time  Frames  Via   Type     Position         Dist Dir
----------------------------------------------------------------------
G4GVZ     30/06 12:21     36  WIDE1       5153.66N 00205.23W  57Km 169°
G4LVV-9   30/06 08:24      6              5208.68N 00212.95W  28Km 175°
G4LVV-9   30/06 08:21     38  WIDE1       5209.23N 00211.73W  28Km 172°
G4GVZ     30/06 07:59      4         D    5153.66N 00205.23W  57Km 169°

If you use this option, and there is a lot of digipeated activity, you may need to increase the size of the MHeard table, to avoid nodes dropping out of the list.


MH_PRESERVE (decimal 16)
~~~~~~~~~~~

Up till now, MHeard lists were lost if the node was rebooted. In some cases this is desirable, but sometimes it can be a nuisance. You now have the option of preserving a port's MHeard list across reboots. The new option has the decimal value 16. You may still clear the list at any time using the MHCLEAR command.

The MHFLAGS OPTIONS are now:

           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 reboots.

All options are enabled by default.

*************************************************************************

[16] BCAST Command
==================

It can be highly frustrating waiting for "NetRom-only" nodes to discover each other after a reboot, so the BCAST command has been added, to force a nodes broadcast. The form is:

	BCAST <portnum>

	Example: "BCAST 6" 

Although this command was intended for test purposes only, it may also be used in CRONTAB.SYS for scheduling nodes broadcasts at specific times, overriding the automatic scheduler. This could be used to stagger the broadcasts to reduce loading on a radio PSU for example.

NOTE: This COMMAND is not to be confused with the DIRECTIVE of the same name, used in XROUTER.CFG, which has a different purpose altogether.

*************************************************************************

[17] Running XRouter As Daemon
==============================

If you wish to run XRouter as a daemon process, simply use the "-d" command line switch when starting the program, for example:

	"./xrpi -d"

It may be "against the rules" but, to avoid confusion, XRouter running in daemon mode uses the same files and folders as it would when when run "normally". Therefore, if you wish to run as a daemon, you must ensure that, XRouter's "working directory" is located on a part of the file system which cannot be unmounted.

In "daemon" mode, you can still see any of XRouter's "windows" by using XRMON.
 
*************************************************************************

[18] Dual-Standard PZT/RTL Chat Links
=====================================

Until now, the links between XRouter chat servers (i.e. those specified by the CHATLINKS directive) were single-standard. For example, if you specified:

	CHATLINKS=VK2DOT,+XE1FH-11

it meant that the link with VK2DOT would exclusively use XRCHAT protocol and the link with Xe1FH-11 would exclusively use W0RLI's Roundtable (aka RTL) protocol, as used by BPQCHAT.

However, as XRouter's chat is tri-standard, cases have arisen where two XRouters want to link both their XRCHAT and RTLchat at the same time. This was not previously possible, because XRouter uses only one SSID for chat.

Rather than pollute the nodes tables with yet another SSID (which would have been the easier solution), the chatlinks can now be dual-standard, meaning that a single chatlink can support both protocols simultaneously.

It sounds easy... It definitely wasnt! XRChat and RTLchat are radically different, and they use their chatlinks differently, so a lot of code had to be remodelled. Therefore I can't guarantee that nothing is broken.

To specify a chatlink as dual-standard, prefix the callsign with an ampersand like this:

	CHATLINKS=&G8PZT-8

The link will now accept both XRchat and RTLchat. Omit the ampersand and the link only responds to XRchat. Replace the ampersand by a plus, and the link responds only to RTLchat.

Please be careful to avoid creating "loops" in the RTLchat system, as it is a bit finicky about such things. It is best to establish RTL links with only ONE other node.

*************************************************************************

[19] Changes to Logging
=======================

Until recently, event logging was controlled by "options", specified initially by the LOG directive in XROUTER.CFG, or by the LOG command.

These options were either "on" or "off", i.e. logging of a particular subsystem was either all or nothing. Apart from CHAT, which had finer control, this was a huge compromise between usefulness and clarity.

Logging now allows finer control, although this is still a work in progress.

The format of the logs is now:

	<time> <level> <system>: <comments>

For example:

	004101 7 CHAT: Peer G8PZT-8 sess 6 timeout
	004101 6 NRL4: Requesting disconnect from G8PZT-8,
			theirCct=2930 ourCct=6
	004101 6 SESS: 6 G8PZT-8@G8PZT-8 SK R:97 S:33
	004121 6 NRL3: L3RTT request to G8PZT
	004121 6 NRL3: L3RTT request to G8PZT-14
	004121 6 NRL3: L3RTT reply from G8PZT, TT=60ms
	004206 7 PROC: PB MAPD

<level> is the event's "priority" level between 0 and 7. The LOWER the number, the higher the importance of the information. Low numbers represent errors and events that must not be ignored, whilst the highest level is for verbose debug information that you would't usually want to log.

Level 6 is for normal operational messages. Level 5 is for notifications that are not errors, but may require attention. Level 4 is for warnings, level 3 for software errors, and level 1 for hardware errors.

Events are only logged if their priority number is equal to or LOWER than the "verbosity" threshold set by the sysop. For example, if a subsystem's verbosity level is 6, normal operational information, warnings and errrors are logged, but debug information isn't. If the verbosity level is 4, only the wwarnings and errors are logged. If the verhosity level is 0, nothing is logged.

Verbosity levels are set using the LOG command, which may also be used in BOOTCMDS.SYS.

	LOG <system> [0-7]

Where <system> is a mnemonic such as CONS (console), NRL3 (Netrom layer 3) and so on. A list of the available menmonics is shown if the LOG command is used with no arguments.

For example, to set the session logging verbosity to 4:

	LOG SESS 4

The older form of the LOG command may still be used:

	"LOG [ON | OFF | 0-16383]"

The numeric argument is discussed in the next section...

*************************************************************************

[20] Log Flags
==============

The option "flags" used in the argument to the LOG directive and command are still in a state of flux. It hasn't yet been decided which flags are useful and what order they should be in, so they may change again. The eventual aim is for the lower numbers to be used for routine logging and the higher ones for occasional debugging (which may generate a lot of logging).

The flags recognised in v503 are as follows:

	Bit	Value	Function
	-----------------------------------------------------------
	0	1	Enable/disable logging
	1	2	Use CRLF instead of LF line endings
	2	4	Log session activity
	3	8	Log TCP/UDP events
	4	16	Log Netrom layer 4 events
	5	32	Log IP/ICMP layer events
	6	64	Log Netrom layer 3/inp3
	7	128	Log ODN activity.
	8	256	Log IDS activity to IDS log
	9	512	Generate PCAP file (use with caution)
	10	1024	Log daemon process events
	11	2048	Log AX25 over TCP
	12	4096	Log AX25 connections etc
	13	8192	Log interface layer events

Most of the above are backward compatible with V502, but please note that PCAP has been moved from 1024 to 512, and AXTCP has moved from 512 to 2048.

For example, to log session layer and Netrom L4 activity in Windows format, you would use "LOG=23" (1+2+4+16) in XROUTER.CFG, or "LOG 23" at the console / in BOOTCMDS.SYS. To log EVERYTHING, it would be 16383, and to log everything except PCAP it would be 15871 (16383-512)

When a flag is "ON", the verbosity level for that subsystem or group of subsystems is set to 6, i.e. "routine information". When the flag is "OFF", the verbosity level is 0.

*************************************************************************

[21] Per-Port CTEXT and CTFLAGS
===============================

CTEXT and CTFLAGS were previously GLOBAL directives in XROUTER.CFG, i.e. all ports inherited the same values. They can now be used within PORT configuration blocks, to override the global values. However there are a couple of differences in how they are used...

Firstly, whilst *global* CTEXT continues to be specified in the usual way as a "block" of text, the PORT equivalent uses one CTEXT directive for each *line* of text. Lines can be up to 255 characters long, and are specified in the order that they are to be replayed. For example...

	CTEXT=This is a *local* node, for local people.
	CTEXT=There is nothing for you here.
	CTEXT=Go away!

Secondly when CTFLAGS is used in a PORT definition block, only the values 0 to 3 are used, because the other values have no meaning at Layer 2.

	0 = Don't send CTEXT to anyone
	1 = Send CTEXT when someone connects to node/port ALIAS
	2 = Send CTEXT when someone connects to node/port CALLSIGN
	3 = Send CTEXT to all incoming AX25 Layer 2 connections.


*************************************************************************

[22] Added CTEXT and CTFLAGS Commands
=====================================

The new commands are as follows. Note that the CTEXT command can be abbreviated to "CT" and CTFLAGS to "CTF".:

	CTEXT <port>			- Displays current text
	CTEXT <port> ADD <text>		- Appends a line of text
	CTEXT <port> CLEAR		- Clears the whole ctext
	CTEXT <port> LOAD		- Loads ctext from CTTEXTn.SYS
	CTEXT <port> NEW <text>		- Replaces existing Ctext
	CTEXT <port> SAVE		- Saves ctext to CTEXTn.SYS

	CTFLAGS <port> [0-3]


Single line ctexts can be added with either NEW or ADD. The former clears any existing text. The latter is OK if there is no existing text.

Upon bootup, if CTEXT is not specified, XRouter looks for the file CTEXTn.SYS, whcre n is the port number. If the file is found, the contents are loaded. Otherwise the global ctext (if any) is used.

If the contents of CTEXTn.SYS is changed, it can be reloaded into memory using the LOAD sub-command. Or if the text is changed on the fly, it can be stored for the future, using the SAVE sub-command.

If <text> specifies a filename, the contents of that file are read "live" every time someone connects, so this is ideal for dynamic ctexts. See the section below.

*************************************************************************

[23] Dynamic CTEXTs
===================

Although unlikely to be used in the UK, the ability to dynamically change CTEXT may be of use in EMCOMM scenarios.

If CTEXT is a filename, the contents of that file are read "live" every time someone connects. That file could for instance be updated by another program, such as an extreme weather detector.

If the filename starts with the 5 characters "CTEXT", e.g. "ctext-news",
that file will be read from the current directory. If it is a fully qualified path starting with "." or "/", there are no restrictions on where the file resides, so long as XRouter is allowed to access it. For example, using the CTEXT command:

	CTEXT 5 new /etc/weather/latest.txt
	CTEXT 6 new ctext-news.txt

or using the CTEXT directive within PORT definition blocks in XROUTER.CFG:

	CTEXT /etc/weather/latest.txt   <-- in the port 5 block
	CTEXT ctext-news.txt            <-- in the port 6 block


*************************************************************************

[24] Booting With MONitor ON
============================

The ability to do this was removed some time ago because there seemed no point in wasting CPU time tracing packets on consoles that were not visible at bootup.

The ability has now been reinstated. If the command "MON ON" is included in BOOTCMDS.SYS, packet monitoring is enabled on the FIRST console only, and that console window is displayed at bootup, instead of the status window.

*************************************************************************

[25] Added BOOTWIN Directive
============================

This specifies the window number to be displayed immediately after bootup. If not specified, or the number is out of range, it defaults to window 6, ie the "overview" window.

Even if BOOTWIN is specified, if MON ON is used in BOOTCMDS.SYS (see above), the first console is displayed instead.

*************************************************************************

[26] Preventing Connections
===========================

There may be a need to prevent connections on a port, either from a troublemaker, or more likely, to prevent another node from establishing a link on your "user access" port.

Until now, EXCLUDE was only usable within a PORT configuration block in XROUTER.CFG. It has now been made available as a run-time command, allowing "on-the-fly" reconfiguration.

Syntax: EXC[lude] <port> [call[,call..] | clear | none]

If <port> is 0, the exclusion applies globally, i.e. to all ports. To avoid confusion,  global exclusions are not shown in port excusion lists.

Examples:	exclude 0 g9mtt			Exclude G9MTT globally
		exclude 4			Display list for port 4
		exclude 4 gd7dr			Add GD7DR
		exclude 5 g8pzt,g2bof.fred	Add 3 calls
		exclude 5 none			Delete all calls
		exclude 4 clear			Delete all calls

The command can be used multiple times, to add one or more callsigns at a time. Callsigns are appended to the list, if they are not already in the list.

NONE and CLEAR can be used interchangeably, and they both clear the list.

There is as yet no way to remove a single callsign, other than remove them all and reinstate the wanted ones. If anyone needs this, let me know.

*************************************************************************

[27] Improved INFO Pages
========================

Introduced in V501, "INFO <nodecall>" connects to the INFO server of <nodecall>, providing that node was also an XRouter. However it couldn't self-connect to its own server. This has now been rectified.

Added "INFO PAGE" command. This displays a text version of the HTTP info summary page,

Added "INFO MORE" command. This displays similar information to the "config" page that is displayed to sysops from the alt-M menu. It gives additional config information that is not displayed on the info summary page.

*************************************************************************

[28] MQTT Daemon
================

This is an inbuilt MQTT client which automatically connects to an external MQTT broker (server). The broker may be on the LAN or in the cloud.

The broker's IP address or hostname is specified using MQTTSERVADDR and its 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 daemon 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 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. Ulitmately it should be possible to provide a full MQTT-based interface to packet radio.

This stalled project is probably a solution without a problem! I'm happy to extend this as far as you like, but I don't have the time to develop web-based application interfaces to use it. If there's any interest in it, let me know.

*************************************************************************

[29] MQTT Broker
================

This is an inbuilt MQTT broker (server), which allows MQTT clients to exchange information with XRouter, with each other, and with an external broker, as mentioned above.

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,

The broker may be enabled on XRouter and/or Linux/Windows IP stacks using the MQTTPORT directive in XROUTER.CFG. The usual port number for MQTT is 1883.

The full spec is too large to be included here, so it will be made available in a separate document.


Subscription Topics:
~~~~~~~~~~~~~~~~~~~~

Subscribing to any of these topics causes XRouter to publish data asynchronously, to the same topic:

	xrouter/event/{nodecall}/blog		Blog events
	xrouter/event/{nodecall}/chat/{evtype}	Chat Events
	xrouter/event/{nodecall}/circuit	NetRom L4 Circuit 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		Wall 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 Transmitted
	xrouter/nr3b/{nodecall}/rcvd		Netrom Traffic Received
	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/{num}   Retrieve blog message
	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}/mail/msg/{num}	Retrieve PMS message
	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/{num}	Retrieve wall message 


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 frame (*1)
	xrouter/put/{nodecall}/blog		Post BLOG article/reply
	xrouter/put/{nodecall}/chat		Send a CHAT message
	xrouter/put/{nodecall}/ipv4		Send raw IP datagram
	xrouter/put/{nodecall}/kiss/{ifacenum}	Send a raw KISS Frame
	xrouter/put/{nodecall}/mail		Send msg/bulletin/email
	xrouter/put/{nodecall}/nr3b		Send raw NetRom (*2)
	xrouter/put/{nodecall}/wall		Post message on WALL

(*1) Without HDLC framing or CRC
(*2) Routable datagrams only, no L3RTT, INP3 or Nodes broadcasts!

*************************************************************************

[30] Teletext Mode
==================

As a result of the interest in "retro computing", several nodes are now running a Videotex application called "Telstar". The output from this application could not be viewed properly on XRouter versions prior to v502x, but a basic "teletext" decoder has now been added.

Due to the limitations of the Linux console, this cannot display the "mosaic" graphics, nor double height / double width characters. Graphics characters are displayed as '#' symbols, and eveything is normal height. Nevertheless, the display is very usable, and is actually easier to read than the original teletext system.

Switching in and out of teletext mode is automatic, and it will also drop out of teletext mode upon disconnection.

Telstar pages are 25 lines high, so in order to display them correctly, the central pane of XRouter's "console" window must be at least 25 lines high. Thus the Linux terminal in which Xrouter runs must be at least 29 lines.

*************************************************************************

[31] Scandic Characters
=======================

It was not previously possible to enter some Scandic characters on the keyboard. Some progress has been made on this, but without a Scandic keyboard and locale I can't test this properly, so it may not work!

*************************************************************************

[32] Callsigns in RoundTable / BPQ Chat
=======================================

Although the full callsign-ssid was being sent to BPQChat, the latter was displaying the callsign with the "-", but without the SSID number, e.g. "g8pzt-".

To avoid confusion, only the callsign is now sent, without the SSID.

Thus you cannot log into the RoundTable / BPQchat system from multiple nodes.

*************************************************************************

[33] BugFix: "KISSTCP Connections Time Out Every 5 Minutes"
==========================================================

When KISS over TCP was used to connect with Direwolf, the connection would close every 5 minutes, and immediately re-open. This has now been fixed.

*************************************************************************

[34] BugFix: "Polled KISS Not Working"
=====================================

A piece of code had been commented out when XR32 was ported from Windows to Linux, and no-one seems to have noticed! Normal KISS was working, but "polled" KISS was not - the polls weren't being sent. The code has now been fixed and soak tested.

*************************************************************************

[35] BugFix: "Private Chat Messages Stored in Wrong Directory"
=============================================================

It made no difference to functionality, but the private chat messages were being stored in the XRouter directory instead of the CHAT directory, as a result of some leftover DOS/Windows backslashes in the file paths. These had been overlooked during XRouter's conversion from Windows.

Private chat messages are now stored in CHAT/privmsgs.txt, as they were supposed to be.

*************************************************************************

[36] BugFix: "Corrupt L3RTT From 64-bit TheNetNode Caused Loss of Alias"
=======================================================================

Until recently, XRouter extracted node aliases from received L3RTT frames, which was OK because L3RTT frames always had a predictable format.

However when TheNetNode1.79 is compiled on a 64 bit platform, some of the fields in the frame can overflow their 10-digit spaces, causing XRouter to extract incorrect aliases.

XRouter is no longer fooled by corrupt fields in received L3RTT frames.

Thanks to Marc-Andre Alpers DO4OA for bringing this to my attention.

*************************************************************************

[37] Fixed "Locked Routes"
=========================

The code for the "locked routes" section of XROUTER.CFG had been disabled years ago, for reasons unknown or forgotten. It's possible that locked routes were deemed undesirable?

As there was some demand for this feature, it has now been reinstated.

Please note that once a route has been locked, removing it from the "locked routes" list does not remove it from the system. To do that you need to delete or edit the XRNODES file. A safer option is to use the ROUTE DROP command to remove the route, then SAVENODES to ensure that it doesn't come back on the next boot.

*************************************************************************

[38] Reinstated "/REcent" Command in Chat Server
================================================

Sub-systems are sometimes "temporarily" disabled while trying to isolate bugs. Unfortunately, their reinstatement sometimes gets overlooked after the bug is found! The chat server's "/Recent" command was one such case. It has now been reinstated, in improved form.

This command previously displayed only the recent messages from channel 1000. It now records and displays messages from all channels.

Messages are stored for 24 hours only, which is mainly a legacy of the memory limitations of DOS. If that is too short, let me know. 

*************************************************************************

[39] Commanding TNC's Into KISS at Startup
==========================================

For KISS TNC's on an ASYNC interface, the CONFIG directive can be used to specify a command which switches the TNC into KISS mode. The command will vary with TNC make and model.

For example, on the Tiny2 this would be as follows:

	CONFIG=KISS ON\rRestart\r

On other TNC's it might be:

	CONFIG=\e@J\r

"\e" sends the ESCAPE character (ASCII 27), and '\r' sends the "carriage return" character (ASCII 13).

The command is sent ONLY at bootup. If there is a requirement to send it any more frequently, let me know.

*************************************************************************

[40] Forcing a Level 2 Connect to a Neighbour Node
==================================================

The "classic" way of doing this is to supply the port number, and connect to the ALIAS of the target node, appending an arbitrary SSID, for example to connect to GB7GH:GLOS, the command would be like this:

	C 4 GLOS-1

As newbie BPQ users don't seem to know about that method, even though it had been used on BPQ nodes since the 1980s, the "new" BPQ method has been added to XRouter, for compatability. This involves prefixing the target node's callsign with an exclamation mark, for example:

	C 4 !GB7GH

*************************************************************************

[41] BugFix: "Hex Values on MPORT Help Panel Are Wrong"
======================================================

The help panel, displayed when F1 (HELP) is pressed after F3 (MPORT), listed port numbers along with corresponding hex values. These values were out of date, showing port 1's hex value as 1 when it should have been 2 and so on.

They have now been corrected, so the port numbers now match the "bit" index in the MPORT number, e.g. bit 0 (value 1) is port 0, bit 1 (value 2) is port 1 and so on.

*************************************************************************

[42] Added / Updated HELP Files
===============================

Like the MAN files, the HELP files had not been updated for many years,
in some cases not since the year 2000. They have now all been updated,
and some new ones have been added.

Plase delete the existing contents of XRouter's HELP directory, and install the new files.

*************************************************************************

[43] Tunnel Interface
=====================

For some reason, it seems this was omitted from the v502 release notes:

		XRLin / XRPi Tunnel Interface
		#############################

		Provisional Documentation

		Revision 1, 6th March 2020


About the Tunnel Interface
==========================

The Linux "tun" interface provides a means of IP-layer communication between user-space programs such as XRPi, and the Linux kernal IP stack.

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

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

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

A persistent tunnel is one that is created at the Linux command line using a command such as "ip tuntap add mode tun dev tun7". Programs can attach to, and detach from, a persistent tunnel at will. The tunnel is not destroyed when the user-space program closes.

XRPi can use either type of tunnel.

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


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

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

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

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

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

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

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

This is where an IP tunnel can be used.


Configuring a Tunnel Interface on XRPi:
======================================

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

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

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

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

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

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

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

	IP ROUTE ADD 192.168.0.0/24 192.168.0.100 3 d


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

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

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

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

a) Simple Method

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

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


b) Manual Method

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

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

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

There are many ways in Linux of achieving the same results, for instance:

   ifconfig tun99 192.168.0.98 pointopoint 192.168.0.99 mtu 1500 up


Finally:
I haven't a clue how to set up Jnos or any other program, so I am hoping the beta testers will add some useful information here.

*************************************************************************

[44] Sysop's Blog
=================

The blog is a text-only, packet radio version of an Internet "web log", free from viruses, trojans, advertising and other Internet nasties,

It is a space, for sysops to post "articles", which other people can "like" or reply to. These articles are not forwarded to other packet systems, but may optionally be published to an MQTT broker.

It is also an attempt to get some "content" onto Packet. After all, without content, what is the point of Packet?
                                                                                
Articles may be created as simply as posting a message to a PMS. Apart from the copmmand line interface, the blog may also be operated via the sysop's web interface, via MQTT, and via REST.

A new directive, BLOGFLAGS is added, the value of which should be the sum of the desired options from this list:

            1 - Enable blog
            2 - Notify sysop (via PMS) of new replies
            4 - Notify sysop (via PMS) of new "likes"
            8 - Publish new posts / replies via MQTT

See the BLOG.MAN file for more info.

*************************************************************************

[45] Message wall / Guestbook
=============================

The "wall" is a public message board / guestbook where users can leave short text messages, comments, suggestions, reminders, observations etc.  Think of it as a text-only version of the old Facebook wall.

Unlike a BBS, wall posts are not forwarded to other systems, and they do not expire. They have no "to" or "subject" fields, they are just a string of text, like a tweet.

The wall may be operated via command line, or via the sysop's web interface, via MQTT, and via REST.

A new directive, WALLFLAGS is added, the value of which should be the sum of the desired options from this list:

            1 - Enable wall
            2 - Notify sysop (via PMS) of new posts / replies
            4 - Publish new posts / replies via MQTT

See the WALL.MAN file for more info.

*************************************************************************

[46] REST interface
===================

The BLOG, WALL and PMS may be operated via a REST interface, whereby data is passed to and from XRouter via JSON within HTTP. This is a proof of concept, and the intention is to interface more subsystems, e.g. CHAT, when time allows.

The point of this is to decouple the data from its presentation, allowing yet-to-be-written applications to obtain, format and present data in whatever form they wish.

I haven't got the time to develop an application to use this interface, so if anyone is keen to use this and provide feedback, I'd love to hear from them.

See REST-BLOG.MAN, REST-WALL.MAN and REST-PMS.MAN for details.

*************************************************************************

[48] Dutch language Support
===========================

The new file NEDERLANDS.SYS contains Dutch language texts, which can be loaded automatically at boot up if required. The quality of the translation cannot be guaranteed. I am still awaiting feedback on that one!

See the LANG command and the MAN file for LANGS.SYS

*************************************************************************

[49] Sysop's Manual via HTTP
============================

A new "Admin" menu option has been added to the sysop's HTTP interface. At present, the only item on the admin page (so far) is a link to the Sysop's Manual. The allows the MAN pages (if installed) to be viewed with a browser, which is much easier than viewing in command-line mode.

Th manual pages are displayed in sections, such as "General commands", "Configuration directives", "Interfacing", "Files", etc.

As it was a rush job, it's not (yet) as hyperlinked as the online version.

*************************************************************************

[50] New PMS Command "RH" (Read with Headers)
=========================

The "R" (read message) command used to display messages in full, i.e. showing all the NTS routing and RFC-822 headers that form the first part of the message body. This has now changed.

Now "R" reads the message WITHOUT headers, displaying only the summary block and the actual message text.

Soometimes it is useful to be able to examine the routing headers, so to replace the previous functionality a new RH (Read with Headers) command has been added. The syntax for RH is the same as the R[ead] command, e.g. "RH 161" reads message 161 with full headers displayed.

*************************************************************************

[51] XRWin - 32-bit Windows Version
===================================

XRPi / XRlin were spawned from Windows-based XR32, around 9 years ago, and XR32 was effectively abandoned at that point. Not because there was anything wrong with it, but because most sysops were going over to Raspberry Pi.

Since then there has been a huge amount of development on the Linux versions, so it would be almost imposssible to unpick the changes and apply them to XR32, to bring it up to date.

There are still sysops who want to run Windows, so I have ported the v503 Linux code back to Windows, to create "XrWin". It is like "XR32 on steroids", with MOST of the features of the Linux versions.

Unfortunately there's no audio support yet, it's only 32-bit, and there are a few minor display bugs. But all it needs is time and some beta testing.


*************************************************************************

[52] Extra Protocol Tracing
===========================

My philosophy is this: "If XRouter sees a packet of any type, via any interface, it nust be able to decode that packet, and present it in a form understandable by humans". Well, techie humans at least!

To that end I have added tracing for DNS (Domain Name System), MDNS (Multicast DNS), SSDP (Simple Service Discovery Portocol), NBNS (NetBios Name Service) and NBDS (NetBios Data Service), as I am often seeing these packets on my LAN.

*************************************************************************

[53] Prevented IP route learning via INP3 on AXIP/AXUDP connections.
====================================================================

"If it's POSSSIBLE to do stupid stuff, a sysop WILL do it" -  And so I did!

You don't need to read the following story, unless you want to laugh at my idiocy.

I needed to test something to do with AXIP (I can't remember the details), so I set up an AXIP link between my "mobile" node (my laptop), and the new XRWin a couple of hundred miles away.  The problem is, my laptop is on mobile broadband, so it can't use AXIP directly. No problem, I simply tunneled it in 44-net over the AXTCP link back to my main node.

So now I have XRWin and XRLin both connected via AXTCP to the main node which is XRPi. The AX25 connections are carrying a 44-net IP payload, and that payload is AX25 over IP. Now it looks like there's a *direct* AX25 connection between MOBILE and XRWIN, completing the triangle. My brain hurts by now.

All worked fine for a few minutes, then it stopped working. Reboot everything -it works ok for a few minutes, then stops again.

To cut a long story short, as soon as one of the nodes heard an INP3 broadcast containing IP address details from the other across the new AXIP link, it assumed that there was a direct IP routing to that node via the AXIP link. So it adjusted the routing table, meaning that the AXIP was now being routed via port 11 instead of port 2, But IP and ARP traffic sent to port 11 is encapsulated in AXIP and sent to port 11 instead of port 2. Hence it recursed forever.

To prevent this happening again, the IP route learning feature is now disabled on "virtual" connections such as AXIP / AXUDP.

This is just one example of how easy it is to screw things up if you have the tools to do so.

*************************************************************************

[54] Added Recursion Prevention and Error Stats to AXIP and AXUDP
=================================================================

I'm not the only sysop to have set up XRouter in a dodgy way. I have seen some very strange configurations, and strongly suspect that they are to blame for most of the "unexplained" crashes. If set up correctly, XRouter won't crash.

As a result of the previous saga I have added code to prevent AXIP and AXUDP from being inadvertently routed up their own exhaust pipe, and have added some error stats to keep track of such conditions.

If your AXUDP / AXIP aren't working, the error stats might give you (and me) a clue why not.

There are no "receive" error stats at present - they will be added later.

*************************************************************************

[55] Added AXIP and AXUDP subcommands to the S[tats] command
============================================================

In order to view the new AXIP and AXUDP stats two new subcommands have been added to the S[tats] command. They are:

	S[tats] AXIP
	S[tats] AXUDP

Note that (at present) "AXIP" and AXUDP" must be given in full, they can't be abbreviated. And they don't (yet) show on the syntax help.

The new stats should be fairly self explanatory:

    3584 frames sent
       0 frames unsent (resolution failure)
       0 frames unsent (no route)
       0 frames unsent (routing loop)
       1 frames unsent (miscellaneous reasons)

"Resolution failure" occurs when IPLINK has been specified as a hostname, and 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.

*************************************************************************

[56] Added Recursion Prevention and Error Counts to IP Stack
============================================================

As previously stated, when examining bug reports I have seen some wierd configurations that are bound to fail, not just involving AXIP and AXUDP. So I have also added recursion prevention to the IP stack, and some stats to record what's going on.

If recursion shows up in the stats, it's a sure sign that XRouter has been configured incorrectly.

*************************************************************************

[57] Added extra IP stats revealed by "S[tats] IP"
=================================================

The "S[tats] IP" command now shows an extra set of "error" stats like this:

    IP NoRoute NoGatewy RouteLoop:         0         0         0
    IP Ignored Rejected Discarded:         0         0         0
    IP Denied TTLExpired NoSocket:         0         0         0
    IP TooBig HostEncap XrEncap:           0         0         0
    IP HdrParam Recursion:                 0         0 

"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 packet is back to the gateway it came from.

"Ignored" means received frames 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 frames dropped because they matched an IP route entry of type "s" (silent discard). No ICMP response is sent.

"Denied" means TCP packets 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 packets 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 required".

"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 IP stack, but failed to do so.

"HdrParam" means packets dropped due to a problem in the IP header parameter list.

"Recursion" counts datagrams that were dropped because they traversed the IP stack too many times.

*************************************************************************

[58] Updated MAN files
======================

Many of the existing 216 MAN (sysop's MANual) files dated from 2013 or earlier, and some of them were no longer valid. A major update has taken place over the past 4 months (which is why the release of version 503 is so late!)

Most of the old files have been reviewed and updated, and over 200 new files have been added. Some topics have been moved from one section to another. 

Plase delete the existing contents of XRouters MAN directory, and install the new files. You can now read them via the sysop's HTTP interface.

*************************************************************************

