NOSaprs 1.15b6
APRS Server & Internet
Gateway for TNOS and JNOS
Designed & Coded by Maiko
Langelaar, VE4KLM
during the period of April 2001
to July 2003
Saturday, July 12, 2003
Table of Contents
Title page 1
Table of contents (this page) 2
What is NOSaprs 3
Why did I write this software 3
Some of the features 3
General overview (how does it
work) 4
What does NOSaprs hear 4
Most of the NOSaprs commands
(very detailed descriptions) 5
Starting the services 16
Setting the unproto path (very
important) 16
Understanding routing - by
message recipient 16
Understanding routing - by
which interface station was last heard on 16
How RF users can opt out of the
internet gateway 17
Email Server – RF users can
send email via APRS 17
The APRS Message Center (a
simple messaging client) 17
Tracking
APRS stations – the APRS heard table 18
Status
information – using the tcp/ip finger utility 18
Status information – via port
14501 and a web browser 19
How to setup the NOS
configuration file - autoexec.nos 20
Miscellaneous stuff and other
notes 22
What is NOSaprs
NOSaprs
is an APRS internet gateway (igate) and server integrated into NOS itself.
Those that are already running JNOS or TNOS internet gateways can easily start
to support their local APRS community by simply getting a NOS binary that
contains the NOSaprs services, and then adding a few extra lines to the
autoexec.nos file. Use an existing RF port (zoo channel), add another port and
radio for 144.390, add multiple RF ports on different frequencies, use a 9600
baud port, use AXIP or AXUDP to get APRS data from other internet gateways
around the world, do whatever you think is possible with your NOS setup.
Why did I write this
First
of all, this software is in no way meant to compete with other APRS software
that is out there. There is some very impressive software available that is
dedicated to APRS, in particular UI-View, which impresses the heck out of me. I
wrote this specifically for the NOS community - the NOS die-hards if I may –
allowing them to participate in the APRS world wide experience without the need
to setup extra and possibly separate systems that may or may not easily fit
into their existing configuration.
If you
try this software, and in the end you don’t like it, or you don’t want to use
it, that’s perfectly fine by me, at least by then I hope you will have gained
some insite and good experiences with APRS in general.
Some of the Features
·
Intercepts most APRS data heard
on any NOS ax25 interfaces, and forwards the data to the APRS internet
system, which in turn allows the data to appear on the maps of APRS client
software throughout the world, as well on internet APRS databases like the
popular www.findu.com site.
·
Allows APRS users on any
NOS ax25 interface, to exchange messages with other APRS users on remote APRS
networks only reachable through the APRS internet system, using the 3rd
party messaging system.
·
Powerfull callsign filters –
currently there are five (5) filters available for a variety of operations.
·
Tracks APRS users heard on all
NOS ax25 interfaces. The system can track callsign, DTI, which ax25 interface
the frame was heard on, and the unproto (digi) path of the frame if any digis
were used. This information is available using finger aprsstat@machine or by web browser using http://machine:14501.
·
When forwarding APRS data to
the APRS internet system, a Point of Entry (POE) callsign is inserted into the
source path header, allowing other systems to identify your machine as the one
which injected the APRS packets into the APRS internet system. This can be
disabled by the sysop if desired.
·
Intercepts MIC-E packets and
forwards them to the APRS internet system (extra options available).
·
Supports routing by message
recipient, allowing APRS users on conventional packet networks to participate
in the APRS scheme of things. Users several nodes away can now join in on the
APRS fun without the need for WIDE, or RELAY, or APRS digipeaters.
·
APRS Email Server. Email can be
handled locally by NOS itself, instead of being sent out to the APRS internet
system for processing. Any APRS user can send internet email, simply by sending
an APRS message to the recipient callsign, ‘EMAIL’ (extra options available)
·
APRS users can opt out of the
IGATE by specifying RFONLY or NOGATE in the unproto path, that way their
packets are not forwarded to the APRS internet system.
·
APRS message center – messaging
client - allowing the NOS sysop, and the general PBBS user, to do message
passing with any other APRS user, either on a remote APRS network only
reachable through the APRS internet system, or through one of the NOS ax25
interfaces for local message passing. This was designed to have a somewhat convers
type of look and feel - some restrictions apply.
·
An HTML based status page,
similar in concept to what aprsd provides, using tpc port 14501. A sample
screen shot of this HTML based page, is shown on the opening page of this
documentation. A text based version is also available using the tcp/ip ‘finger’
utility. See the ‘Tracks APRS users’ feature mentioned earlier on this page.
Users can click on callsigns on this page, and get a direct link to mapping
information from sites like the popular www.findu.com site.
·
Flexible broadcast options.
NOSaprs has separate broadcast parameters for the internet side and the RF
side. Each side has it’s own set of parameters, in which you can configure the
broadcast interval, status text, and position information. If you don’t want
broadcasts at all, they can be shutoff if desired.
·
Responds to ?PING? or ?APRST
requests from APRS internet system and from the RF side. You can also send a
message to NOSaprs, which is logged to a file (ie, /nos/spool/aprs/aprs.txt).
All messages to and from NOSaprs logon callsign are logged (including sysop and
PBBS message center traffic).
·
Accept's connections from other
programs like UI-View, WINaprs, and other NOSaprs stations so that they can
forward APRS data to us and not get the firehose of data sent back to them.This
is also ideal for those systems that have very low speed (or low bandwidth)
connections, and simply want to advertise their position and other information
to the world and not hear back from the world.
·
Experimental WIDE and WIDEn-N
digipeater built in (can be switched on or off on the fly).
·
Can broadcast to RF, specific
position and status packets received from the APRS internet system, not just
APRS messages anymore. All broadcasts use the 3rd party identifier
to stay legal.
·
Other features are added as
time permits.
General Overview (how does it
work)
The
NOSaprs software has the minimum functionality required to be an APRS internet
gateway (igate), so it should be configured to connect to tcp port 1314 (the
message port) of any aprsd or java aprs server that is part of the APRS
internet system. At startup time, NOSaprs will go through a list of servers,
connecting to the first one it can. Once connected, it will continuously
receive messages from the server, and route those messages out a preconfigured
NOS ax25 interface. There are callsign filters available so that the sysop can
control which messages are allowed to go out, and which are not. APRS frames
received on any NOS ax25 interface are sent to the APRS internet system,
using the same connection we receive messages on. Keep in mind that NOSaprs
only connects to 1 host server at any time, unlike other APRS servers that can
be configured for multiple connections to different host servers, for the sake
of redundancy, etc. NOSaprs can also take positional and status information
from the APRS internet system and broadcast them out the preconfigured NOS ax25
interface. There are callsign filters available to control this aspect as well.
I
strongly recommend you go over the NOSaprs commands further on in this
document, to get the best understanding for how this stuff works. The commands
are quite well documented, and I have gone into some fairly heavy detail,
including extra information on the mechanics of how all this stuff is supposed
to work. If I have missed anything, or something does not look right, please
let me know so I can correct it.
What does NOSaprs hear
NOSaprs
will hear any APRS packets that have a destination call of ‘BEACON’, ‘ID’,
‘EMAIL’, or any callsign starting with the letters ‘AP’, or any callsign that
matches the APRS MIC-E callsign requirement. The number of digipeaters in the
packet header, or whether any of the digipeaters were used to repeat the
packets, is of no importance. NOSaprs will hear it all, and process it
accordingly. I have fairly strong validation rules in place, so not everything
heard is sent to the APRS internet system. For example, 3rd party
packets heard on any of the NOS ax25 ports, are NOT forwarded to the internet
system, since they’re not supposed to be.
Most of the NOSaprs commands
Most of the NOS commands related to NOSaprs start
with the word ‘aprs’ and are as follows.
1.0 aprs <subcommand>
The
current subcommands can be obtained by entering the command, ‘aprs’, at the NOS
prompt :
Net> aprs
valid subcommands:
bc flags calls client contact
hsize interface
internal listen
locator log logon server email
mice status
Net>
Next we will summarize the
above commands, from left to right, top to bottom …
1.0.1
aprs bc …
NOSaprs
broadcasts it’s own status and position information at regular intervals. There
are two groups of broadcasts, one to RF, the other to the APRS internet system
- they are independent of each other. Use these commands to configure the
content of these broadcasts, and whether you want them active or not.
Net> aprs bc
Usage: aprs bc [ver|rfver] [on|off]
aprs bc [stat|pos|rfstat|rfpos]
[data]
aprs bc
[timer|rftimer] [minutes]
Net>
1.0.1.1 aprs bc [stat | pos |
rfstat | rfpos] [status or position text]
This
command lets you set the text of the status and position information that you
want broadcast by the NOSaprs server. There are four possible options here :
stat - status text to be
broadcast to the APRS internet system side.
pos - position text to
be broadcast to the APRS internet system side.
rfstat - status text to be sent out the default ax25 interface side.
rfpos - position text to
be sent out the default ax25 interface side.
If you want the same text broadcast to both the
APRS internet system side and RF, then you only need to define the stat
and pos options. If the rfstat and rfpos options are not defined,
they will default to the values set for the stat and pos options.
For example :
aprs bc stat "IGATE - 441.050 Mhz -
ve4klm@ve4umr.ampr.org"
aprs bc pos
"4953.22NI09718.35W&"
I now
use ‘=’ as the dti (Data Type Identifier) for the position broadcasts (since
NOSaprs is capable of messaging), so make sure you do not change the format of
the above information. Only change the numerical coordinates - degrees, not
decimal - to suit your own position. By default, the status text above will
have the NOSaprs version prepended to it when it is broadcast, so in actually
fact the broadcast will look like the following :
NOSaprs 1.15b6 IGATE - 441.050 Mhz - ve4klm@ve4umr.ampr.org
You can
switch this suffix off using the command, ‘aprs bc ver | rfver’, described a
bit further on.
1.0.1.2
aprs bc [timer | rftimer]
[interval in minutes]
This
command lets you set the interval of the status and position broadcasts. The RF
broadcast has it’s own timer, as does the APRS internet system broadcasts. If
you don’t want a particular broadcast, then either set the interval to the
value of zero, or don’t define the timer(s) in the autoexec.nos file. By
default, the timers are off.
1.0.1.3
aprs bc [ver | rfver] [on |
off]
This
command simply flags whether you want the NOSaprs version information prepended
to the status broadcast(s) or not. The RF broadcast has it’s own flag setting,
as does the APRS internet system broadcast. By default, the version is included
in the status broadcast.
1.0.2
aprs flags …
NOSaprs uses flags for some of
it’s configuration. You can enter the command, ‘aprs flags’ at the NOS prompt,
and it will show you the current settings (the ones below are the default
flags) :
Net> aprs flags
-debug -badpackets -monitor +poe +dtiheard +bconlyifhrd -digi
Net>
Flags are set using the
command, ‘aprs flags +option’ , and unset using the command, ‘aprs flags
–option’.
Next we will describe each of
the availabe options in detail.
1.0.2.1
debug
If you
run into problems and are lucky enough to be able to reproduce the problems,
then you can enable the debug option, which will write additional debug or
trace information to the NOSaprs log file.
1.0.2.2
badpackets
If you
want to track parsing errors, or want to know about APRS frames that had errors
in them or did not meet some requirement of the general APRS specification,
then you can enable the badpacket option, which will write error messages to
the NOSaprs log for any packets that have formating issues.
1.0.2.3
monitor
If you
want to monitor the exact data you are receiving from the internet side, you
can eable the monitor option. This is simply an extension to the debug
facilities. Be careful with this option, as the information is currently dumped
to the NOSaprs log file. If the internet traffic is high, the log file will
fill up really fast.
1.0.2.4
poe
This
option is used to enable or disable the injection of the Point of Entry (POE)
callsign into the source path header when forwarding packets to the APRS
internet system. By default, the POE is turned on. It can be switched off of
course, but there really is no reason to do so. The injection of the POE
callsign allows one to trace which APRS igate was responsible for sending the
APRS packet to the APRS internet system.
1.0.2.5
dtiheard
Allows
the sysop to enable or disable tracking of the DTI (Data Type Identifier)
character in the APRS heard table (not the same as the ax25 heard table). The
APRS heard table can get quite big if we get the same station using a whole
bunch of different DTI values (meaning an assortment of different type of APRS
packets). Quite frankly, there is no point tracking the DTI for general use. I
use it to get an idea of the type of traffic on frequency, and some of you may
want to do the same. If this flag is enabled, then the 14501 pages will show
the DTI information. If this flag is not set, the you will not see the DTI
information displayed on the 14501 page.
1.0.2.6
bconlyifhrd
The
purpose of this flag is to minimize the amount of RF traffic generated by the
APRS internet gateway. I mean, what is the point of broadcasting a 3rd
party message from the APRS internet system to RF if the station for which the
message is intended was never heard within range of the NOSaprs server. Some
people will have different views and preferences of course, that’s why this
flag was added. By default, this flag is set, and it only applies to APRS
messaging.
If this
flag is not set, then of course NOSaprs will send the message out the interface
on which the message recipient (station) was last heard. If the station was not
heard, then the message is sent out the default aprs interface, which is
configured with the command, ‘aprs interface’, discussed further on.
Note : this flag does not
affect the callsign filters in any way. All it does is limit RF transmissions !
1.0.2.7
digi
NOSaprs
has a very experimental built-in APRS digipeater. It can digipeat WIDE and
WIDEn-N packets, and will track for duplicates, so there should be none
of this endless bouncing back and forth of packets between NOS and other
digipeaters on frequency. This option should only be used if you have no other
APRS digipeater in your area, and you want to provide an interim or emergency
digipeater. I’m willing to work on this some more, but only if people express
an actual interest in it.
By
default this flag is unset. I recommend you leave it that way if you are in a
well established APRS arena.
1.0.3
aprs calls …
NOSaprs has a series of
callsign and ‘callsign pattern’ filters to deal with different areas of
functionality.
Net> aprs calls
Usage: aprs calls [fwdtorf|bantorf|ignorerf|postorf|stattorf]
*[callsign &| patt
ern list]
Net>
These
are very powerful commands, so be very carefull on how you implement them. You
can run these command on the fly for all the available filters, so subsequent
instances of any command will simply delete the existing filter, and create a
new one to replace it. Also, note that the wildcard feature detailed in the
fwdtorf section applies to all of the available filters (very powerful indeed).
There are currently five (5) filters
available to the sysop. Next we will go over each of them in detail …
1.0.3.1
fwdtorf
This
filter is specific to APRS messaging and broadcasting of 3rd party
messages. It allows the sysop to configure which messages from the APRS
internet system are allowed to go out the RF interface. The filter looks at the
recipient callsign of the message to determine if it goes out RF or not. The
best way to show this is by example, for instance take a look at the following
:
aprs calls fwdtorf ve va k*6 k*4k
The above
example will only gate messages to RF for any messages where the recipient
station has a callsign that begins with either ‘ve’, or ‘va’, or starts off
with the pattern, ‘k*6’, where the ‘*’ character is a wildcard (meaning
anything). Note the ‘*’ wildcard is for one character position only ! In other
words, the pattern, ‘k*6’, will allow any callsigns beginning with ‘ka6’, or
‘kb6’, or ‘kp6’, etc. If you want to wildcard more than one position you would
need multiple ‘*’ characters. For example, ‘**6’, would allow any call where
the 3rd character from the start of the callsign had the digit 6 in
that position. Putting a trailing ‘*’ is redundant and is not necessary (for
example, ‘ve4*’ does no more than using just ‘ve4’ as the pattern).
Note:
The way one defines the callsigns and/or ‘callsign patterns’ above applies to
all of the filters, not just this one. You can use wildcard definitions like
above with the remaining four (4) filters (very powerful).
1.0.3.2
bantorf
This
filter is used in conjunction with the fwdtorf filter above, and also only
applies to APRS messaging and broadcasting of 3rd party messages.
There may be specific callsigns or callsign patterns that pass through the
fwdtorf filter that you still may not want to send out the RF interface. For
example, suppose you want messages for VE4 and VA4 to be gated to RF, but at
the same time you don’t want messages for VE4BAD and VE4XXX to be transmitted
out the RF interface. You could use a combination of filters as follows :
aprs calls fwdtorf ve4 va4
aprs calls bantorf ve4bad ve4xxx
Note:
these callsigns are strictly examples, with no relationship what-so-ever to
actual callsign holders.
1.0.3.3
ignorerf
This
filter is used against rf, axip, or axudp stations heard by NOSaprs. Suppose we
have a couple of stations sending ‘undesireable’ aprs traffic (no particular
kind), and we don’t want that stuff to be injected into the APRS internet
system, without having to shutdown the entire NOSaprs server. You can try this :
aprs calls ignorerf ve4bad ve4xxx
The callsigns
will still appear in the APRS heard table (and on the 14501 and finger
information pages), but the packets FROM them will NOT get sent out to the APRS
internet system. Again, the above is just an example, no relationship to actual
callsign holders.
1.0.3.4
postorf
NOSaprs
is capable of processing position information from the APRS internet system,
and broadcasting it out the RF interface. This filter lets you select for which
stations you want their position information broadcast to RF. For example, suppose
you want to want the position information of your friends on the other side of
the continent gated to your local frequency, you could use something like this
:
aprs calls postorf ve3mch-4 aa6hf lw2dtq
ve7tsi-7
1.0.3.5
stattorf
NOSaprs
is capable of processing status information from the APRS internet system as
well, This filter is identical to the postorf above, but works on status
packets, not position packets. An example follows :
aprs calls stattorf ve3mch-4 aa6hf
It is
important to note that the ‘fwdtorf’ and ‘bantorf’ filters focus on message
receipients of messages coming from the APRS internet system, while the
‘ignorerf’ filter focuses on the source of the aprs traffic (not just messages,
but all traffic type) heard from the RF side. The ‘postorf’ and ‘stattorf’
filters focus on the source callsigns of position and/or status packets coming
from the APRS internet system.
Also,
with any traffic we get from the APRS internet system that requires us to gate
the information to the RF interface, we transmit it using the NOSaprs logon
call as the source callsign, and use the standard 3rd party
identifier. We don’t want to be transmitting packets that have a source address
of the station that sent the original information. That’s the whole idea of the
3rd party identifier.
1.0.4
aprs client …
NOSaprs
can accept connections from APRS clients on tcp port 14825. These are what I
call send only connections, in other words a client can connect to
NOSaprs to send information to the APRS internet system, and not get the
firehose of data normally received if they were to connect direct to a
non-NOSaprs internet server.
It is
important to note that any messages received by NOSaprs from the APRS internet
system that are destined for callsigns belonging to online clients are diverted
to those clients, giving them the minimum requirement to adhere to Bob
Bruninga's key principle of everyone having APRS messaging capability with rest
of the world. This client server is ideal for stations that simply want to
monitor APRS traffic (like satgates) or for Weather stations. This is also
ideal for stations that have low speed or low bandwidth connections from their
client side.
Blind
APRS client connections are not allowed !!! If an APRS client wants to connect
to NOSaprs, they must first be configured to do so by the NOSaprs sysop. At
present, up to 10 client connections are permitted.
Net> aprs client
usage: aprs client [add|delete|list|kick]
*[parameters]
Net>
Next we
will discuss each of the subcommands needed to maintain client configurations.
1.0.4.1
add
The
syntax for adding a particular machine to your client list is as follows :
aprs client add <ip address of client
machine> <keep alive interval> <info port>
The
<ip address of client machine> is self explanatory.
The
<keep alive interval> is in seconds (not minutes), and is a required
parameter. Most APRS clients will terminate a connection if nothing has been
heard after a certain amount of time. That makes sense to do, since the nature
of the internet is that things can suddenly go offline without warning. NOSaprs
will send a simple status message to the connected client every few minutes
(configured by the keep alive interval) so that the connection is not
terminated by the client. Setting the keep alive value to zero will disable the
status messages. Each client has their own independent keep alive interval,
since some client software may be more relaxed than others when it comes to
‘how long to wait before we terminate a connection’.
The
<info port> is optional. If set to 0, the html link for the client’s
status in the 14501 page is disabled, but if the info port is set to a non-zero
value, the html link will use that value as the port to connect to. The default
port is 80 (standard http port), and by default there will always be a html
link.
Example
- we wish to allow a UI-View APRS client (ip address 10.1.1.1) to connect, and
we need to make sure that the client receives at least something every 30
minutes. One could configure the following :
aprs
client add 10.1.1.1
1800
Note,
the UI-View software to my knowledge does not support a 14501 page or similar
(yet), so we should actually disable the html link to the host machine, and
instead configure this particular client as follows :
aprs
client add 10.1.1.1
1800 0
1.0.4.2
delete
To
delete a client from the list (usually done from NOS prompt if you ever need to
it), the syntax is :
aprs client delete <ip address of
client machine>
An
example follows below :
aprs client delete 10.1.1.1
1.0.4.3
list
To list
all the configured APRS clients, issue
the following command :
aprs clients list
1.0.5
aprs contact …
The
14501 status webpage has a section called ‘contact information’. NOSaprs gives
you a few options on how you wish to have this displayed.
Net> aprs contact
use: aprs contact [t|m|h] [contact
information]
currently: not defined
Net>
You can
have a text only field, an html link to another webpage, or a mailto link so
that users can simply click on it to send you an email. The command syntax is
as follows :
aprs contact <mode> <contact
information>
The
<mode> is a one character code that denotes how the <contact
information> is to be displayed :
t - means the contact info is displayed as
is.
m - means the contact info will be
enclosed in a ‘mailto:’ link
h - means the contact info will be enclosed in a standard ‘html’ link
The
<contact information> is sort of self explanatory and should meet the
requirements of the mode.
Some
examples are shown below :
aprs contact t “maiko AT langelaar DOT
net”
aprs contact m maiko@langelaar.net
aprs contact h http://www.langelaar.net
I did
this in part to raise awareness. The ‘mailto:’ links were a great thing, but
unfortunately they are under major abuse by spammers now. Spambots continously
visit gazillions of websites, newsgroup archives, and who knows what else, just
to collect the ‘mailto:’ links it finds. You now have the option of not using a
‘mailto:’ link if you wish. Having a link to a club website is probably the
best idea instead. You don’t have to have anything configured either if you
want. If you don’t define a contact, then ‘not available’ will appear on the
14501 status webpage.
1.0.6
aprs hsize …
NOSaprs
has a heard table specifically for APRS stations or ‘stations / DTI
combinations’ heard. This is a separate heard table totally unrelated to the
standard NOS ax25 heard table. Technically it would have been a great idea to
combine them into one heard table, but that would have involved a fairly
complex change to code, that I was not prepared to do at the time.
Note
that this command actually creates the APRS heard table, not just defines the
size. If you don’t run this command at all, then no heard table is created. The
size parameter simply configures the maximum number of station callsigns or
‘station callsign / DTI combinations’ that can be held in the table before the
oldest entries start to get overwritten again. This command can be run on the
fly, so subsequent instances of the command will delete the old heard table,
and create a new empty one (with a new size if desired). The command syntax is
as follows :
aprs hsize <number of entries>
For
example, to configure a heard table to hold up to 50 entries, you could use
this :
aprs hsize 50
It is
very important to note the affect of the dtiheard flag with respect to the APRS
heard table. Using the above example, if the ‘dtiheard’ flag is not set, you
technically have room for 50 different callsigns. If the ‘dtiheard’ flag is set
though, you may very likely not be able to get the last 50 callsigns - for
example what if a particular callsign has been heard using four (4) or five (5)
different DTI characters. That is not unusual in the APRS realm, because those
stations can easily issue position reports, status reports, and they do
messaging with other stations, etc. The point is that the <hsize>
parameter does not necessarily mean that the heard table will have heard the
last 50 stations.
1.0.7
aprs interface …
In
order for NOSaprs to gate information to the RF world, we need to define an RF
port. The cool thing with the NOS software in general is that the port can rf,
or axip, or even axudp. The syntax to configure is :
aprs interface <port>
For example, to use the JNOS or
TNOS port (interface) ‘ax0’ as the default port for NOSaprs, try this :
aprs interface ax0
1.0.8
aprs internal …
This is
a kludge of sorts that I had to implement a few years ago. The days of NOS
installations that have two (2) public IP addresses is probably coming to an
end. There are a lot of NOS internet gateways in general now that use only one
(1) public IP address, with linux doing the encapsulation, or not even that,
the sysop is simply doing IP masquerading (no encapsulation period). At one
time, my development system at the University of Manitoba was configured to use
two (2) public IP addresses, with NOS doing all the encapsulation. I had
trouble passing udp packets within NOS under that arrangement, so I used this
command to deal with it. Most likely you will never need to use it, so that’s
all I will say about it for now.
1.0.9
aprs listen …
This command is used to start
or stop the NOSaprs server. To start NOSaprs, use this :
aprs listen on
To stop NOSaprs services
(usually never done anyways), use this instead :
aprs listen off
1.0.10
aprs locator …
One of
the features of the 14501 status webpage is that you can configure (what I
call) a locator URL, such that if a visitor to the 14501 webpage clicks on any
of the callsigns showing, the browser will go to the URL with the callsign
appended to it. That enables visitors to click on any callsign and get a
instant and direct link to the world famous http://map.findu.com
website, as well as other sites. Syntax is as follows :
aprs locator <URL>
What’s
a URL you say ? It’s another way of saying ‘the full pathname to a website’.
For example, you can configure your locator to point to the popular findu.com
site as follows :
aprs
locator “http://map.findu.com/”
Make
sure you include the last slash (/) character or else you will get a ‘site not
found’ type of error when a visitor tries to click on the callsign link on your
14501 status webpage.
1.0.11
aprs log …
NOSaprs
has a separate log file for logging APRS related issues – that stuff should
really be kept out of the main NOS log file. The log does not have to be
defined, but is probably a good idea to have one to keep track of operations.
The syntax is as follows :
aprs log <full pathname to logfile>
For example, if
you want to log to the file /nos/spool/log/aprs.log, do this :
aprs log /nos/spool/log/aprs.log
You can switch
the logging off at any time using this instead :
aprs log off
It is a
good idea to make this the very first of the aprs commands within your
autoexec.nos file. Also, make sure the directory path specified in the full
pathname above actually exists. If the directory path does not exist, then it
won’t be created for you either (sorry, an oversite on my part).
1.0.12
aprs logon …
This
command sets the callsign that NOSaprs uses when logging into the APRS internet
system. This callsign is also used when NOSaprs has to broadcast APRS traffic
out any RF interface.The source callsign of the transmission will be the logon
callsign. The syntax for this command is as follows :
aprs logon <callsign>
For
example, to set the NOSaprs callsign to VE4KLM-10, you could use this :
aprs logon ve4klm-10
1.0.13
aprs server …
NOSaprs
needs a connection to the APRS internet service if it is to send and receive
APRS traffic. Unlike other igate software such as the aprsd application,
NOSaprs only maintains one (1) connection to any one (1) server at any one
time. Systems like aprsd use multiple connections at any one time for the sake
of redundancy, which is quite interesting actually. I don’t support that (yet),
and quite frankly, for NOS environments I don’t see a need for it (yet). Only
time will tell perhaps …
Net> aprs server
usage: aprs server [add|delete|list|kick]
*[parameters]
Net>
Next we
will discuss each of the subcommands needed to maintain the server
configurations.
1.0.13.1
add
The
syntax for adding a particular machine to your server list is as follows :
aprs server add <ip address of APRS
server> <tcp port> <info port>
The
<ip address of APRS server> is self explanatory.
The
<tcp port> defines which port on the server machine we want to connect
to, and is a required parameter. The port value depends on the type of server
machine you are connecting to. Since NOSaprs was designed to be at minimum a
message gateway, I would suggest you use port 1314. If you want to also gate
positional and status information from the APRS internet system, then you will
have to use a busier port like tcp port 23 or port 10152. There is plenty of
literature available on the web regarding available ports for many of the
different APRS servers that are running world wide.
A
word of warning - when connecting to an APRS
server, there is no point connecting to any other
port than port 1314, if all you want to do is monitor or support APRS
messaging. At time of print, port 1314 is the port that will let you do
messaging with the least return of data from the APRS internet system, so
connecting to other much busier ports will only load NOS down for
nothing, and add to the cpu utilization.
The
<info port> is optional. If set to 0, the html link for the server’s
status in the 14501 page is disabled, but if the info port is set to a non-zero
value, the html link will use that value as the port to connect to. The default
port is 14501 (standard port for most APRS core servers), and by default there
will always be an html link.
Example
– to add the APRS server, orlando.aprs.net, to our list, use the following
command :
aprs server add orlando.aprs.net 1314
You can
add up to four (4) servers to the list. NOSaprs will rotate through them as
needed. If NOSaprs is not able to connect to the first server on the list, it
will try to connect to the second one in the list, and so on, and so on, if
need be. You must have a minimum of one server configured or else the system
stays off-line.
1.0.13.2
delete
To
delete a server from the list (usually done from NOS prompt if you ever need to
it), the syntax is :
aprs server delete <ip address of APRS
server>
An
example follows below :
aprs server delete orlando.aprs.net
1.0.13.3
list
To list
all the configured APRS servers, issue
the following command :
aprs server list
1.0.13.4
kick
If for some reason you suspect a problem with the APRS internet system server to which NOSaprs is currently connected to - for example, it’s no longer sending you data or seems dead - then you can issue this command to deal with it, instead of waiting for NOSaprs to check for inactivity. Syntax is as follows :
aprs server kick
This will force NOSaprs to try and terminate the current connection so that it can move on to the next server in the list. This may not always work - tcp/ip timeouts can sometimes take a long time to resolve.
1.0.14
aprs email …
This
command configures how NOSaprs should handle APRS email messages received from the
RF side.
Net> aprs email
use: aprs email [passthru|local|block]
currently: local
Net>
NOSaprs
will never handle APRS email messages from the APRS internet side for obvious
reasons.
Next we
will discuss each of the options (subcommands) and what they are used for.
1.0.14.1 passthru
The
‘passthru’ command tells NOSaprs to pass the email message on to the APRS
internet system and hopefully it will be processed there somewhere. As of the
date and time of this document, the internet system uses an email server that
is run by one of the Sproul brothers (authors of Winaprs).
1.0.14.2 local
The
‘local’ command tells NOSaprs to use the NOS built-in SMTP service to send the
email to the recipient, instead of passing it to the APRS internet system. By
using this mode of operation, the email message from RF will never reach the
APRS internet system, and NOS itself will try and send the mail using it’s own
internal server (one of the more beautiful things about developing in the NOS
environment).
1.0.14.3 block
Self explanatory, this command
tells NOSaprs to ignore APRS email messages completely.
1.0.15
aprs mice …
This
command configures how NOSaprs should handle MIC-E packets received on any RF
interface.
Net> aprs mice
use: aprs mice [ignore|passthru|convert]
currently: passthru
Net>
Next we
will discuss each of the above options (subcommands) and what they do.
1.0.15.1 ignore
Self explanatory, this command
tells NOSaprs to ignore MIC-E packets completely.
1.0.15.2 passthru
The
‘passthru’ command tells NOSaprs to pass MIC-E packets as is (unaltered) to the
APRS internet system. This is now the default mode. If you are connected to the
APRS internet system, then leave this mode as is. Do not change it unless you
have very good reason to.
From
what I understand, it used to be common that APRS internet gateways converted
MIC-E packets before passing them onto the APRS internet system. Apparently
this is no longer preferred and in actual fact has caused problems
(inconsistent posit reports, etc). Frankly, I have yet to find any official
note that supports this issue, but several of the so called APRS gurus have
essentially requested that no more conversions be done, and that APRS
internet gateways should now be passing MIC-E as is and unaltered.
1.0.15.3 convert
If for some reason you want
conversion of MIC-E packets before they are sent to a remote server (likely you
are not connected to the APRS internet system, and perhaps you’re experimenting
with other applications), then this command will tell NOSaprs to convert any
MIC-E packets that it hears before they are sent.
1.0.16
aprs status
Instead of using ‘finger
aprsstat’, you can now enter the command ‘aprs status’ at the NOS prompt :
Net> aprs status
Ver: NOSaprs 1.15b6, Uptime: 0:00:00:13, Call: VE4KLM-10,
Interface: 430
Server connection:
Server Port Connected Pkts In Bytes
Pkts Out Bytes
209.114.215.25 10152 0:00:00:00 0
0 0 0
128.143.202.191 10152 0:00:00:00 0
0 0 0
No APRS traffic heard so far
Net>
Starting the services
There are a couple of NOSaprs related commands that do not
start with the word ‘aprs’.
1.0
Starting and stopping the 14501
status webpage server
To start the 14501 service, use
the command ‘start 14501’. To stop it, use ‘stop 14501’.
1.1 Starting and stopping
the APRS client services
To start the 14825 service, use
the command ‘start 44825’. To stop it, use ‘stop 44825’.
No, it’s not your imagination –
44825 is the correct term, even though it does not match the client port.
1.2 Starting and
stopping the NOSaprs server itself.
This is done using the ‘aprs
listen’ command – check on page 12 of this document.
Setting the unproto path
By
default, all APRS traffic from NOSaprs is sent out the aprs RF port using the
unproto path of ‘APZ115’.
You can
change the unproto path throught the standard NOS ‘ax25 route add’ command. For
example, if you would rather have NOSaprs send APRS packets out the RF port
using the path ‘APZ115 v WIDE’, then configure the following in your
autoexec.nos file :
ax25
route add APZ115 ax0
WIDE
This is
where NOS shines - I did not have to write any special routing commands for
this application, as many of the standard NOS functions and commands fit in
perfectly. Incidently, there are alot of different opinions on what the ideal
unproto path are. It varies from one APRS community to the other. There is a
lot of information freely available on the various APRS news groups and mailing
lists, as well as the general internet at large. I will leave it up to you the
sysop to research this for yourself.
Understanding routing - by
message recipient
NOSaprs
has the ability to route APRS messages based on the callsign of the recipient
of the message. If you program a route to a specific callsign, using the
standard NOS ‘ax25 route add’ command, then NOSaprs will actually try to route
any APRS messages destined for that callsign, using the the preprogrammed route
for that callsign, effectively overriding the default unproto path. If a
message comes in, NOSaprs will know exactly where to digipeat the frame based
on the recipient callsign of the message.
That’s
a powerful option in my opinion and provides some degree of flexibility for
users that want to play with APRS on conventional packet networks where APRS
digipeaters are not available, and all that is in place are the conventional
packet network nodes of yesterday (many of them unfortunately disappearing
forever).
Note : routing by recipient is purely an option, and is not
forced on the sysop at all.
Understanding routing - by which interface station was last
heard on
NOSaprs
can route APRS messages (coming from the APRS internet system) out the RF
interface that the recipient station was last heard on, instead of through the
preconfigured APRS interface. Of course, if the station was not heard, then the
message is gated out the default interface. Because of this feature, users on
any NOS ax25 interface should now be able to message with other APRS stations
via the APRS internet system. Routing between NOS ax25 interfaces on the same
machine is not implemented (yet).
How RF users can opt out of the internet gateway
There
may possibly be RF users that do not want any of their APRS packets to be sent
to the APRS internet system. If those users wish to opt out, they can insert
the callsign ‘NOGATE” or ‘RFONLY’ into their unproto path on their APRS client.
They will still appear on the APRS heard table, but their traffic will not be
gated to the APRS internet system.
Email Server – RF users can
send email via APRS
Any
APRS user on the RF side or on any of the AXIP or AXUDP wormholes can send a
simple one (1) line message to any internet email account, or to any local BBS
or mailbox account. All you have to do is address your message to the callsign,
‘EMAIL’. The format of the one (1) line message is best illustrated with some
examples :
The
following example will send a message to my internet email address, maiko@langelaar.net.
maiko@langelaar.net hi
Maiko, this is a test
The example below will send a message to my BBS
account on our local TNOS box.
ve4klm hi Maiko, this is a test message
The
first field (no spaces) is interpreted as the email address or mailbox account
to which you want the message sent. The remainder of the information is the
body of the message. How and where it gets sent is effected by how you have
your NOS rewrite file configured. Keep that in mind when offering this service.
NOSaprs
can be configured to handle email requests in 3 ways :
· pass all request to the APRS internet system for processing.
· ignore (block) all email requests.
· handle email requests locally (use the built in NOS smtp
services).
Yes you
heard that right. NOS has it’s own built in SMTP services. The default
configuration is to have NOS handle the email request locally. This is a
powerful feature, because the NOS rewrite rules are automatically implemented
with any built in mail functions. You can technically have an email request
forwarded to a local FBB bbs system, instead of to the internet. For more
information on configuring this part, see the ‘aprs email’ command documented
on page 14.
Note : if NOS itself is handling any email requests, they are never
sent to the APRS internet system. Any requests from the APRS internet system
are NOT processed for obvious reasons, although they easily could be, it’s just
one line in the source code that prevents this J.
The APRS Message Center (a
simple messaging client)
NOSaprs
features a simple, but possibly useful APRS Message Center of sorts, for both
the PBBS user and the sysop (from the NOS console). I've tried to give it the
look and feel of a typical convers session. It’s a very simple interface, which
I hope to put more effort into down the road. The current release of NOSaprs
requires that the PBBS user have TELNET permission if they are to use it.
To
activate the message center, just use the command 'aprsc' from either the PBBS
prompt or the NOS console. Some restrictions apply - it can not be run from within
SYSOP mode, and the PBBS user that has the same callsign as the NOSaprs server
itself is not allowed to use it from the PBBS, they must use it from the NOS
console instead, due to technical reasons I won’t get into. The message center
can be used to chat with stations reachable through the APRS internet system,
as well with local stations through the NOSaprs RF interface. Note, any
incoming messages that have a message id are only acked once, unlike the
various windows clients out there that can send multiple acks. That is on my
list of things to complete.
Tracking APRS stations – the
APRS heard table
NOSaprs
lets you dynamically configure a heard table of any size. The heard table keeps
track of APRS users heard on all NOS ax25 interfaces, including the type of DTI
character seen per callsign, on which ax25 interface the station was heard on,
and the unproto (digi) path used. The DTI is short for Data Type Identifier,
which defines the type of APRS information being passed. That way, the sysop or
other users can see who is doing APRS on any of the NOS ax25 interfaces, and
what type of APRS traffic is involved. The tracking of the DTI can be turned
off if desired. See the ‘aprs flags’ command on page 6 for more details.
Status information – using the
tcp/ip finger utility
To
display the APRS Heard Table as well as the status of server and any client
connections, one can use the finger command. For example, to show the APRS
heard table and connect status for the NOSaprs machine ‘ve4umr.ampr.org’, a
remote user could run the following command :
finger aprsstat@ve4umr.ampr.org
and it will give you something
like what is shown below (information from an older version shown) :
[ve4umr.ampr.org]
APRS status at
ve4umr.ampr.org
Ver: TNOSaprs
1.12, Uptime: 5:16:03:10, Call: VE4UMR-5, Interface: 430
Server connection:
Server Port
Connected Pkts In Bytes
Pkts Out Bytes
128.143.202.191 1314 0:01:50:00 3388
260032 12 662
*
209.114.215.25 1314 3:08:33:02
158451 12451159 661
38896
198.88.21.2 1314
0:03:34:43 10163 816118
33 1916
No APRS clients
connected at this time
APRS traffic
heard:
Callsign DTI
Since Pkts Other Info (I=Interface, P=Path)
ve4bbs !
0:00:10:24 331 -
ve4klm !
0:00:05:28 127 P ve4pkt* ve4pkt-8*
ve4klm > 0:00:05:27 120 P ve4pkt* ve4pkt-8*
ve4klm-4 :
5:06:09:27 10 P ve4pkt* ve4pkt-8*
ve7rxd !
0:00:23:03 237 I tsi, P kaipgu*
Of
course the ‘ve4umr.ampr.org’ machine must have the FINGER server running for
this to work. The sysop on any NOSaprs machine can now get the aprsstat
information for their own machine, by entering the ‘aprs status’ command at the
NOS prompt. They could of course enter ‘finger aprsstat’ as well, but if they
do not have the local FINGER server configured, then that would not work for
them.
Please refer to the next
section, for more information about what the above data means.
Notes
: the ‘*’ character beside a particular
server entry indicates the server to which NOSaprs is currently connected with.
If you don't see the ‘*’ character at all, it means that NOSaprs is not
currently connected to any of the servers in the list. It will try every 30
seconds to make a connection. What was particularily interesting about the
above listing, was the fact that the ve4umr TNOS box was also receiving APRS
packets from an AXIP wormhole that it had with a gateway in VE7 land. J
Status information – via port 14501 and a web browser
The
information from the finger command can also be made available in the form of
an HTML page, which quite frankly is a much more elegant and flexible way to
display information. Think about it, what is the ideal application client
nowadays ? Every PC comes with one, and the application developer like myself
does not have to worry about spending time writing and maintaining client
software that a user would otherwise have to download to their PC in order to
view the status information. It’s called a web browser.
If you
have NOSaprs configured to run the 14501 server, then you can use any web
browser to get the tracked information discussed in the previous section. I
added this feature because I saw it used by the aprsd software – I liked it, I
agreed with the idea, and I think it’s the way to go. A sample screen shot of
the webpage generated by NOSaprs is shown on the opening page of this user
documentation.
For any
user to access the page, they would enter a URL similar to the following in
their web browser :
The
14501 page is split into several sections – 1) General Information, 2) Server
Connection, 3) Client Connections (if configured), and 4) APRS Traffic Heard
(if configured).
1) General
Information
|
Machine |
hostname configured for the NOS machine running NOSaprs |
|
Uptime |
length of time the entire NOS system has been up |
|
Callsign |
APRS callsign used by NOSaprs – see ‘aprs logon’ command on
page 13 |
|
Interface |
default ax25 interface used by NOSaprs – see ‘aprs interface’
command on page 12 |
|
Contact Info |
sysop contact information - see ‘aprs contact’ command on
pages 10 and 11 |
2) Server
Connection
Remember,
NOSaprs only maintains one (1) connection to any one (1) host server at a time,
unlike other APRS servers that have multiple connections for the sake of
redundancy. With the 14501 page, the host that is currently connected to will
appear highlighted in yellow. If there is no highlighted entry, it means that
there is no active connection to any server at this time.
|
Server |
ip address of a remote APRS server – see
‘aprs server’ command on page 13 |
|
Port |
tcp port to connect to on the remote
server – see ‘aprs server’ on page 13, typical value is 1314 |
|
Connected |
total time we have been connected to
server, or if we are no longer connected, this is the length of time we were
last connected to the server for. The display format is DD:HH:MM:SS |
|
Pkts (Bytes) In |
total number of packets and bytes we have
received from the APRS internet system |
|
Pkts (Bytes) Out |
total number of packets and bytes we have
sent to the APRS internet system |
|
Since |
time that has elapsed since we last heard
something from the remote server. The display format is DD:HH:MM:SS. This
field is only available on the 14501 page, not the finger info. |
There
is a html link on each servers listed in the Server Connection section. These
links are by default configured to access port 14501 of that particular server.
See the ‘aprs server’ command on page 13 for more information on how to
configure the html links.
3) Client
Connections
NOSaprs
can have up to 10 APRS clients attached through port 14825. If any clients are
configured, you will see a list similar to the Server Connection list in the
previous section, but with an additional column for the callsign of the client.
Clients with active connections to your NOSaprs will be highlighted in the
color yellow (just like the connected
server). Inactive clients entries will simply reflect the last information that
was available when the client was connected. Keep in mind that any of the
configured clients can use a different callsign each time they login. Clients
are configured for which ip address they are coming from, not who they login
as.
|
User |
callsign used by the APRS client when
logging into NOSaprs 14825 server |
|
Server |
ip address of the APRS client – see ‘aprs
client’ command on pages 9 and 10 |
|
Port |
tcp port will always be set to 14825
(just for information purposes) |
|
Connected |
total time the client has been connected
to NOSaprs, or they are no longer connected, this is the length of time they
were last connected to NOSaprs for. The display format is DD:HH:MM:SS |
|
Pkts (Bytes) In |
total number of packets and bytes we have
received from the APRS client |
|
Pkts (Bytes) Out |
total number of packets and bytes we have
sent to the APRS client |
|
Since |
time that has elapsed since we last heard
something from the APRS client. The display format is DD:HH:MM:SS. This field
is only available on the 14501 page, not the finger info |
4) APRS
Traffic Heard
Note,
if the NOSaprs ‘dtiheard’ flag is not set, then the DTI column will not be part
of the display, since it will not be tracked in that case. Please see the ‘aprs
flags’ command on page 6 for more info on the DTI flag.
|
Callsign |
callsign of the station originating the
APRS packet |
|
DTI |
APRS Data Type Identifier of the packet |
|
Since |
time since the last packet was heard. The
display format is DD:HH:MM:SS |
|
Pkts |
number of packets heard for this station
or ‘station / dti’ combination |
|
Other Info |
if the last packet was heard on an ax25
interface other than the NOSaprs default interface, then the name of the
interface will appear (marked with an ‘I’ for interface). If the
packet header had any digipeaters, they will be displayed (marked with a ‘P’
for path), and any digipeaters that repeated the packet will be marked with a
‘*’ character |
How to setup the NOS configuration file - autoexec.nos
It is
best to run all your aprs commands after all other NOS intiatializations are
completed – in other words at the very end of the autoexec.nos file. The
following gives you a checklist approach to setting up your configuration file.
Note the capitalized IF word – meaning you don’t have to use that particular
entry, it’s just there for a reference incase you decide you want to do that
particular item. These are example entries, make sure you change it to match
your own needs. I hope it helps.
# Bare minimum (mandatory) commands.
aprs log /nos/spool/log/aprss.log
aprs logon ve4klm-10
aprs interface 430
# IF you want NOSaprs to broadcast it’s
status and position
aprs bc stat "Server - 441.05 Mhz –
ve4klm@ve4klm.ampr.org"
aprs bc pos
"4948.53NI09707.95W&"
aprs bc timer 60
aprs bc rftimer 30
# IF you want a APRS heard table
aprs hsize 20
# IF you are going to run a 14501 server
aprs contact "http://www.langelaar.net"
aprs locator
"http://map.findu.com/"
# IF you plan on connecting to the APRS
internet system
aprs server add 209.114.215.25 10152
aprs server add 209.114.215.25 1313
aprs server add 128.143.202.191 10152
# IF you plan on having APRS clients
aprs client add 44.135.124.62 14825
aprs client add 10.1.1.2 23 0
# IF you want to gate messages to RF using
callsign
# filters - Be VERY CAREFULL how you
configure this
aprs calls fwdtorf ve4 va4 ve3mch*** ve7
aprs calls postorf ve4 va4 ve3mch***
aprs calls stattorf ve4 va4 ve3mch***
# IF you want to ignore particular RF
stations
aprs calls ignorerf ve4bad ve4xxx
# If you want to keep messages from internet
system
# off the frequency for particular stations
after they
# have passed through the fwdtorf filter.
aprs calls bantorf ve4bad ve4xxx
# IF you want an email mode other than
‘local’
aprs email block
# That should do it – START UP NOSaprs !!!
aprs listen on
# IF you want 14501 service
start 14501
# IF you want to accept clients
start 44825
Miscellaneous stuff and other notes
Although
APRS was meant for mobile applications, there’s no reason why those people
running xNOS for their end user stations, could not configure a simple beacon
on their NOS systems. For example, Bob, ve3tok, configured the following beacon
in his JNOS, using the NOS ‘ax25 bctext’ command :
ax25 bctext “!4313.13N/07955.25W- VE3TOK TCP/IP 44.135.85.10
Hamilton, Ontario”
If you
visit the website, http://www.findu.com,
this is how his station will appear :
Here’s
an older screen shot below, of how your NOSaprs server itself might show up on
the findu.com site.
That's
all the documentation for now. Note, that I no longer make any distinguishment
between JNOSaprs and TNOSaprs anymore – it’s just plain NOSaprs now. Please let
me know if you see any mistakes or ommissions. Thank you for trying this
software out, I hope you find it useful (and fun of course).
73 de Maiko Langelaar / VE4KLM