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

                 APRS Internet Gateway (IGATE) notes
                 -----------------------------------

               This revision dated: 11th November 2001


I didn't feel like writing beautiful documentation, so the following 
random notes will have to suffice for now...

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.  If you don't have an APRS port and an internet 
connection you don't need to read any further.

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 stuff 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".  There are various web sites 
which may assist your search, e.g. "www.dididahdahdidit.com/" (what a 
difficult and error-prone address to type!).   I suggest you ask 
questions on the APRS newsgroups if you are unsure, but if you're 
reading this file you probably know more than me about APRS anyway :-)

In IGATE.CFG you may specify as many servers as you wish, each on a 
separate line with the following format:

         SERVER <address>:<port>

         e.g. SERVER 128.196.58.1:1314

The current version doesn't support name resolution, so you MUST 
supply the IP address not the domain name. The port number must be 
separated from the IP address 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.  This is probably a 
crummy algorithm, whose only merit is that it distributes the load 
across various servers, and I may have revised it by the time you read 
this!  The behavious 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 sucessive tries.

         Specifies the number of seconds to wait between sucessive 
         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
~~~~~~~~~~~~~~~~
It is most unlikely that you will find an internet server which 
provides a feed tailored exactly to your needs, so Xrouter's Igate 
contains powerful packet filters, which can be applied both to traffic 
gated to the Internet, and traffic coming from it.  The filtering 
rules are specified in IGATE.CFG using IFILTER (internet to packet) 
and PFILTER (Packet to internet) statements.

The general form of the filter statements is:

         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#@@@*     *    :*

This 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 ( ":" is the data type indicator for a message).

The '\' (escape) character causes the next character to be interpreted 
literally, instead of as a wildcard, e.g. "\*" will match '*' and "\\" 
will match '\'.

Using a caret '^' at the start of any field will invert the sense of 
the whole test, causing any matching packets to be REJECTED. For 
example:

         IFILTER ^M7ABC  *    *
         IFILTER *       ^APZ244*   !*

The first statement will reject all packets from M7ABC, whereas the 
second will reject all static position reports sent to the destination 
address 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.  
If you feel this isn't enough, let me know.  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.  It's debateable 
whether or not this ought to happen - if you know better, let me know.  
This decoding takes place before filtering.

You should be VERY careful when designing your fiter 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 
RF, so I suggest as a start you include only traffic FROM your 
compatriots, and TO them (to include UI-VIEW messages).


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 DIGIFLAGS.  
You should add the following values:

          64   Enable gating from Packet to Internet.
         128   Enable gating from Internet to Packet.

Packets accepted (i.e. passing IFILTER) from the Internet will be 
broadcast on ALL ports which have bit 7 of DIGIFLAGS set, so be 
careful not to lazily set a value of 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:

         1     Record Igate daemon start and stop events.
         2     Record Inet server connections / disconnections.
         4     Record frames sent from Internet to Packet.
         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.  If the logfile grows too big, DOS may take an 
appreciable time to perform the disk writes if you aren't running a 
write cache.  This might affect router performance, so you are advised 
to periodically rename or otherwise remove the logfile, 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 it 
is simple to change the configuration simply by editing the file using 
the PZTDOS line editor, then re-starting the daemon.  Editing can take 
place while the daemon is running because the file is only read at 
start up.

The daemon may be started automatically when Xrouter boots, by 
including the line IGATE=1 somewhere in the "global" section of 
XROUTER.CFG.


Getting an Internet Connection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
None of the above is of any use if you haven't got some means of 
getting a connection to an Internet APRS server.  Until I've finished 
the dial-up support in Xrouter, you have no choice but to use an 
external router to make the actual connection, unless you are 
fortunate enough to have a spare static IP address and an academic net 
connection. Windows 98 (and presumably Linux) can be configured to 
"share" an internet connection, be it of the "dial-up" or "always-on" 
type.

I chose to use Windows 98 with a dial-up connection, since the machine 
was already in use for my email and web activities.  You will need an 
Ethernet connection between your Windows machine and your Xrouter 
machine (unless win98 supports non-dialup SLIP ??).  If Xrouter is 
located on the Windows machine, you will need two Ethernet cards in 
that machine, as it can't share a card - sorry :-(

You will also need to install (if not already installed) Windows 
"Internet Connection Sharing" (ICS).  A wizard will guide you 
painlessly through the process of screwing up your machine :-) No, 
seriously I think my troubles arose because I already had several IP 
addresses in use on that machine and was unsure what I was doing.  If 
you know anything about ICS, please share your wisdom to make this 
document more useful! (I know next to nothing about Windows)

Basically, ICS configures your windows machine's Ethernet port with 
the "private" IP address 192.168.0.1, and you simply configure other 
computers on the Ethernet LAN to use any address between 192.168.0.2 
and 192.168.0.255. You should choose the option to use a static IP 
address not a "server assigned" address.

On the Xrouter machine you need to install a suitable Ethernet card 
driver plus ETHDRV.EXE, and set up an Ethernet port (see XROUTER.DOC 
for details).  The port should be configured to use one of the 
"private" IP addresses other than 192.168.0.1 - you may do this by 
setting the "global" IP address and overriding it on the radio ports, 
or by setting only the Ethernet port to use the private address.

Finally, you need to set up IP routing to and from the Windows 
machine.  If the wizard has done its job properly, Windows 98 will 
automatically route all "private" IP packets to the ethernet port, and 
all you have to do is tell Xrouter how to route stuff to Windows.  I 
can't be precise on this, since your requirements will be different to 
mine, but basically you must arrange to route packets addressed to the 
Internet towards 192.168.0.1 on the Ethernet port.  You can either do 
this using a ROUTE DEFAULT or using ROUTE ADD's for specific 
addresses.

For example, in my case I have ROUTE ADD statements which route radio-
reachable 44-land datagrams out on the appropriate radio port.  I then 
have a "ROUTE ADD 192.168.0.0/24 * 14 d" which allows Xrouter to send 
datagrams directly to my other machines on port 14 (the ethernet LAN), 
a "ROUTE ADD 44.0.0.0/8 x x" which routes all other 44-land datagrams 
to my neighbour, and finally a "ROUTE DEFAULT 14 192.168.0.1 d" which 
routes everything else to the Windows machine for sending to the 
Internet.


Finally
~~~~~~~
If it doesn't work, it's because you haven't configured it correctly!

If I've left unanswered questions, please email me at

      g8pzt@blueyonder.co.uk

73, Paula G8PZT
