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
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 :
bc flags calls client contact hsize interface
internal listen locator log logon server email
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]
184.108.40.206 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 - email@example.com"
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 - firstname.lastname@example.org
You can switch this suffix off using the command, ‘aprs bc ver | rfver’, described a bit further on.
220.127.116.11 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.
18.104.22.168 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
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.
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.
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.
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.
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.
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.
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 !
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
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 …
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).
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.
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.
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
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]
Next we will discuss each of the subcommands needed to maintain client configurations.
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
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
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
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 email@example.com
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 …
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]
Next we will discuss each of the subcommands needed to maintain the server configurations.
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.
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
To list all the configured APRS servers, issue the following command :
aprs server list
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]
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.
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).
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).
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]
Next we will discuss each of the above options (subcommands) and what they do.
Self explanatory, this command tells NOSaprs to ignore MIC-E packets completely.
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.
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 Port Connected Pkts In Bytes Pkts Out Bytes
22.214.171.124 10152 0:00:00:00 0 0 0 0
126.96.36.199 10152 0:00:00:00 0 0 0 0
No APRS traffic heard so far
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, firstname.lastname@example.org.
email@example.com 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 :
and it will give you something like what is shown below (information from an older version shown) :
APRS status at ve4umr.ampr.org
Ver: TNOSaprs 1.12, Uptime: 5:16:03:10, Call: VE4UMR-5, Interface: 430
Server Port Connected Pkts In Bytes Pkts Out Bytes
188.8.131.52 1314 0:01:50:00 3388 260032 12 662
* 184.108.40.206 1314 3:08:33:02 158451 12451159 661 38896
220.127.116.11 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
hostname configured for the NOS machine running NOSaprs
length of time the entire NOS system has been up
APRS callsign used by NOSaprs – see ‘aprs logon’ command on page 13
default ax25 interface used by NOSaprs – see ‘aprs interface’ command on page 12
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.
ip address of a remote APRS server – see ‘aprs server’ command on page 13
tcp port to connect to on the remote server – see ‘aprs server’ on page 13, typical value is 1314
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
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.
callsign used by the APRS client when logging into NOSaprs 14825 server
ip address of the APRS client – see ‘aprs client’ command on pages 9 and 10
tcp port will always be set to 14825 (just for information purposes)
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
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 of the station originating the APRS packet
APRS Data Type Identifier of the packet
time since the last packet was heard. The display format is DD:HH:MM:SS
number of packets heard for this station or ‘station / dti’ combination
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 – firstname.lastname@example.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 18.104.22.168 10152
aprs server add 22.214.171.124 1313
aprs server add 126.96.36.199 10152
# IF you plan on having APRS clients
aprs client add 188.8.131.52 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
# IF you want to accept clients
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 184.108.40.206 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