javAPRSFilter User's Guide 2.0b01 and above This guide is divided into 5 sections: Section 1 - Introduction Section 2 - Program Requirements and Description Section 3 - Configuration Parameters Section 4 - Filter definitions Section 5 - Installation Instructions javAPRSFilter is Copyright (c) 2003 - Roger Bille SM5NRK Use of the software is acceptance of the agreement to not hold the author or anyone associated with the software liable for any damages that might occur from its use. javAPRSSrvr is Copyright of Pete Loveall AE5PL. APRS is a trademark of Bob Bruninga Other trademarks included in the following text are recognized as belonging to the respective trademark holders. ***************************************************************************** Section 1 - Introduction javAPRSFilter is a Server Adjunct to javAPRSSrvr. As a server adjunct it works as a filter to add more traffic to the defined ports that is not normally sent through. It can, for example, provide regional feeds without any extra application and multiple javAPRSSrvr's running, all in one application. javAPRSFilter is written in Java and works closely with javAPRSSrvr. In addition it provides a dynamic filtering that the user him/herself can define and modify without affecting the other connected clients. The idea is to only send the information to the connected clients/systems that they require; this will reduce the load and bandwidth requirements. In general it is very very few systems that need the full feed and it is the full feed connections that eat up the bandwidth. This user guide should be used together with javAPRSSrvr user guide. It is written for the sysop of javAPRSSrvr and not an end user quide. The evolution of this filter depends on feedback, issues, requests, bugs etc passed back to the author at roger.bille@telia.com. ***************************************************************************** Section 2 - Program Requirements and Description javAPRSFilter has the same requirements as javAPRSSrvr since it work together as one application. javAPRSSrvr checks at startup if a Server Adjunct is available (like javAPRSFilter). If one exist it is run as a single entity. javAPRSFilter requires javAPRSSrvr version 3.0b01 or higher. javAPRSFilter provides an extra filtering to pass additional packets to the client based on a filter definition. This is in addition to what javAPRSSrvr pass through the particular port. javAPRSFilter can be used on these javAPRSSrvr ports: msgOnlyPorts, hubAndMsgPorts, clientOnlyPorts and readOnlyPort. The filter can be defined in 4 different methods.The single quotes around the word definition below should NOT be entered. 1) A default filter based on javAPRSSrvr port. This is done through additional parameters in the javAPRSSrvr configuration file. The default filter can be used for regional feeds. The default filter can be override by the user in any of the following methods. 2) As part of the user logon string sent to the server when the client connect. user SM5NRK pass 12345 vers Program Version filter 'definition' The key thing is the additional of the filter keyword and anything behind that is used as the filter definition. It is important that filter is preceded by 7 words separated by a single space. Some client software authors have said they will add support for this into their applications. 3) Sent as a separate comment line to the server. This looks like this: # filter 'definition' The # in the beginning is required. This is only for application support since users cannot create this line by themselves in the normal available APRS applications, unless they use a telnet application or other interactive applications. 4) A client user can send an APRS message with filter definition. This must be sent from the connected user directly to the server userCall. Since javAPRSSrvr is case sensitive and since most APRS client application always use capital for calls in messages you will need to name your server with all capitals. Otherwise, will this method not work. The message body should be like this: filter 'definition' By sending filter? a message will be sent back with current filter definition. ***************************************************************************** Section 3 - Configuration Parameters javAPRSFilter use the same configuration file as javAPRSSrvr, for more information see javAPRSSrvr User's Guide. All javAPRSFilter parameters are prefixed with sa (Server Adjunct). There are 3 different parameters and they are check in order. If #1 exists it is used, if it does not exist the #2 is check etc. The parameter valus is the same for all. #1 saDefaultFilter;IPAddress;port= This can be used if you have multiple IP addresses on your system and want to define filter definition based on IP. saDefaultFilter;213.180.75.122;14580= #2 saDefaultFilter;port= Same as #3 but follow #1 syntax saDefaultFilter;14580= #3 saDefaultFilter'xxxxx'= This will set the default filter for a particular port 'xxxxx' on javAPRSSrvr above. For example: clientOnlyPorts=14578,14579 saDefaultFilter14578=r/55/-4/600 saDefaultFilter14579=r/63/16/1000 will provide a UK feed for all connections to javAPRSSrvr port 14578 and Nordic feed on port 14579. The port 14578 must have been defined in one of msgOnlyPorts=, clientOnlyPorts=, hubAndMsgPorts= or readOnlyPort=. saDefaultFilter14578=r/55/-4/600;t/n will provide a UK feed together with all NWS traffic. ***************************************************************************** Section 4 - Filter definitions The default filter is not to pass anything in addition to what javAPRSSrvr will pass. So an msgOnlyPorts will pass all messages and nothing else until a filter definition is added. Multiple filter definitions can be setup separated by a single space. If any of the filters find a match the packet is passed. Below are the available filters: r/lat/lon/dist Range filter: Pass traffic within dist km from lat/lon lat and lon is signed integer degrees, i.e. negative for West/South and positive for East/North. Up to 3 range filters can be defined at the same time to allow better coverage. p/aa/bb/cc... Prefix filter: Pass trafic with fromCall that start with aa or bb or cc... b/call1/call2... Budlist filter: Pass all traffic from exact call: call1 and call2 t/poimntqsu Type filter: Pass all traffic based on packet type. One ot more be defined at the same time, t/otq is a valid definition: P = Position packets O = Objects I = Items M = Message N = NWS Weather W = Weather T = Telemetry Q = Query S = Status U = User-defined For weather type filter also positions packets for positionless weather packets are passed. For full list of commands see User's Guide ***************************************************************************** Section 5 - Installation Instructions Copy all the files from javAPRSFilter.zip to your javAPRSSrvr installation directory and restart javAPRSSrvr. You can see in the status pages if javAPRSSrvr has found javAPRSFilter.