
                      XROUTER INTERIM DOCUMENTATION
                      =============================

			     APRS Server
			     -----------

		  This revision dated: 16th July 2002



Purpose Of This Document
~~~~~~~~~~~~~~~~~~~~~~~~
"Interim" documentation is that which hasn't yet been incorporated into
the sysop manual.  It is intended to provide easily-accessible and
printable guidance for the configuration and use of new and possibly
experimental features, and is not guaranteed to be complete, accurate,
or permanent.  As development proceeds and feedback is received, the
software and this documentation may be modified.  When the development
cycle is complete, the information herein will be incorporated into the
sysop manual, and this document will be discontinued soon afterwards.

  ====================================================================


Xrouter includes a rudimentary APRS server, which enables suitable
APRS clients, such as UI-View, to connect to it on your LAN and
exchange APRS traffic. The number of simultaneous clients is not
limited.


TCP Port Number
~~~~~~~~~~~~~~~
The server listens for incoming connections on TCP port 1448.  There is
a tradition of choosing port numbers which represent the frequencies
used by APRS, so I chose that port number because many European countries
use 144.800 MHz, hence it is easy for me to remember (sorry USA :-).


Overview Of Server
~~~~~~~~~~~~~~~~~~
The following APRS frames are sent to clients:

 - APRS traffic heard on 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 frames 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 is running).


Registration & 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 will use in combination with the callsign to verify the
user.  A verified user may send traffic to local RF ports, or if
IGATE is active, via other IGATES.

If the user has not registered his copy, 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 frames 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 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, frames to the client may be discarded.


Local <> Internet Server Gating
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If IGATE is not running, no frames will be gated to or from the
Internet.

Frames received from the Internet are not gated to clients unless
they satisfy the IFILTER filtering rules in IGATE.CFG.  Likewise,
frames received from clients are not gated to the internet unless
they satisfy the PFILTER rules.

Frames in "third party" format, frames which do not include the
network identifier "TCPIP" in the digi path, and frames which include
the dummy callsigns NOGATE or RFONLY in the digi path, are not gated
to the Internet.


Using UI-View as a Client
~~~~~~~~~~~~~~~~~~~~~~~~~
Select Setup/APRS Server Setup.

In the box marked "Select A Server", enter the hostname and port
number of Xrouter's APRS server, e.g. "myserver:1448" or
"192.168.0.2:1448".  (On my Windows98 system, neither form would work
until I added a suitable entry into the HOSTS file in the WINDOWS
directory.)

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 is unregistered, you will be able to log on 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


Finally
~~~~~~~
If this document doesn't answer your questions, *PLEASE* tell me,
either by email: g8pzt@blueyonder.co.uk
or by packet: G8PZT @ GB7PZT.#24.GBR.EU


-----------------------------------------------------------------------
Copyright (c) 2002 Paula Dowie
 