Online Amateur Radio Community Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== HOWTO Use QTTermTCP With XRPi / XRLin ======

29 July 2023, G8PZT

NOTE: This is a "quick and dirty" howto. Please feel free to refine it,
add pictures, whatever.. 

QTTermTCP is a very popular "terminal" program for Packet Radio, written
by G8BPQ. It can be used with BPQ node, as well as with other Packet
programs, including XRouter. This document focuses on how to set up
XRouter so that it can be used by QTTermTCP. It assumes you already have
working copies of both QTTermTCP, and XRouter (i.e. XRPi or XRLin)
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 either TELNETPORT and/or RLOGINPORT =====

QTTermTCP requires a TCP "port" number to connect to (note this is a TCP
"service number" not a PORT on XRouter).

Connections to TELNETPORT receive a more verbose welcome text than those
to the RLOGINPORT, but QTTermTCP will happily use either.

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:

<code>
sudo setcap cap_net_bind_service=pe xrpi
</code>

(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:

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

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:

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

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

Note: In "Single Window" mode, QTTermTCP will not accept incoming
connections while it is connected to XRouter. However in "tabbed" or
"MDI" mode it will.


===== Monitor Traffic =====


XRouter will send monitor traffic to QTTermTCP, but it will be in XRouter
format, not BPQ format, i.e. it will look like this:

<code>
	 *** 14:40:51 port 4 rcvd:
	AX25: G8PZT>G8PZT-1 <RR R R4>

	 *** 14:41:00 port 4 rcvd:
	AX25: G8PZT>G8PZT-1 <I C R4 S4> ilen=20 pid=207 NET/ROM
	  NTRM: G8PZT-8 to G8PZT-9 ttl=25 cct=0100 <DISC REQ> 

	 *** 14:41:00 port 4 sent:
	AX25: G8PZT-1>G8PZT <I C R5 S4> ilen=20 pid=207 NET/ROM
	  NTRM: G8PZT-9 to G8PZT-8 ttl=25 cct=D208 <DISC ACK> 
</code>

The displayed port numbers are XRouter's PORT numbers not QTTermTCP's.

If your XRouter ports are numbered consecutively from 1, they will agree
with the port mumbers under QTTermTCP's "Monitor" tab. If however
XRouter's port numbers don't start at 1, or have gaps, QTTermTcp's
"Monitor" tab will list consecutively numbered ports, with the XRouter
port numbers in brackets like this:

<code>
	Port 1 (2) "Ethernet LAN"
	Port 2 (4) "Link to KIDDER"
	Port 3 (5) "Test Port 1"
	and so on...
</code>

===== Corrupted Display =====


Older versions of QTTermTCP (e.g. 0.0.58) have a bug which loses some
data packets, causing a corrupted display. This was reported to G8BPQ
and the fixed version should by now be available.

===== And Finally: =====


Please report any errors, omissions or compatibilty issues to

g8pzt@blueyonder.co.uk

or to the xrouter mailing list (where you will also find the latest
versions of XRouter) at

http://groups.io/g/xrouter

XRouter documentation can be found at http://ohiopacket.org/xrpi