LEGAL STUFF

DESCRIPTION

FILES

Documenation Files:

aprsddoc.html                   This file.
ports.html                      Detailed info about aprsd ports
revisions.txt                   Detailed list of revisions by version number
q.htm, qalgorithm.htm           Q construct docs by Pete Loveall.

Executable files:

aprsd				The APRS server executable
aprspass                        Computes aprs passcodes from callsigns
aprsd.init                      Script that starts and stops aprsd

Configuration files:

aprsd.conf                      Main configuration file for aprsd
user.deny			List of users with restrictions placed on them
welcome.txt			This file is sent to users when they connect
INIT.TNC			This file is read into the TNC when the server starts
RESTORE.TNC			This file is read into the TNC when the server closes

				

Log Files:

aprsd.log			Created by server to log all user connections
thirdparty.log			Third party packets gated to RF
udp.log				Data from the UDP port logged here
rf.log				Data from our TNC after being digipeated
history.txt			Created by the server when it closes to save the 
                                history buffer. Data is read when it restarts.


Install files:

INSTALLDAEMON			Installation script for running as a daemon 
INSTALLPGM			Installation script for running as a program
REMOVE				UnInstall script - deletes /home/aprsd2/*

FILE LOCATIONS

/home/aprsd2
	aprsd
        aprspass
        user.deny
	welcome.txt
	INIT.TNC
	RESTORE.TNC
	aprsd.log
	thirdparty.log
	rf.log
	udp.log
	aprsd.conf
	history.txt


/etc/rc.d/init.d
	aprsd.init

/etc/rc.d/rc3.d
	link to aprsd.init

/etc/rc.d/rc5.d
	link to aprsd.init

/etc/rc.d/rc6.d
	link to aprsd.init


 

INSTALLING AS A DAEMON

Note that this also compiles the program if the executable "aprsd" does NOT exist in the source directory. To re-compile updates in this directory you must do: "make clean" then "make".

• Login as root.
• Copy the archive into your home directory.
• Issue the following command:
• tar zxvf aprsd215.tgz
• Of course you already did it or you wouldn't be reading this ;-)
• cd aprsd215
• Note: The following command will also compile the source files
• ./INSTALLDAEMON
• cd /home/aprsd2
• Now make any changes you may require to these files (in /home/aprsd2/):
  Note: The install program will not overwrite these if they already exist.
  • aprsd.conf
  • user.deny
  • welcome.txt
  • INIT.TNC
  • RESTORE.TNC

Starting and Stopping the Server

You can also start it as a daemon by using the -d option. eg: ./aprsd -d

The serial device for TNC data and tcp port numbers are set in the /home/aprsd2/aprsd.conf file. You can edit this file in the directory you used to uncompress the distribution files then run INSTALL to make the changes effective. INSTALL also will copy the distribution welcome.txt, INIT.TNC and RESTORE.TNC to /home/aprsd so be sure you make changes to these in the distribution directory before running INSTALL.

To stop the server go to the /etc/rc.d/init.d directory and enter "./aprsd.init stop". To restart enter "./aprsd.init start" . Also, you can use the "service" command. eg: service aprsd.init start .

RUNNING AS A PROGRAM

First, stop the aprsd daemon by entering: /etc/rc.d/init.d/aprsd.init stop or "service aprsd.init stop" .

It can be re-started as a user program changing to the /home/aprsd2 directory and typing its name " ./aprsd " Note: you will need to be logged on as root unless your user name has write priviliges on the directory /home/aprsd2 and all the files in it.

If you want to be able to log on as remote sysop and take control of the TNC you will need to add a "tnc" group to the /etc/group file. See "REMOTE TNC SYSOP ACCESS" below for more details.

INSTALLING AS A PROGRAM

Note that this also compiles the program if the executable "aprsd" does NOT exist in the source directory. To re-compile updates in this directory you must do: "make clean" then "make".

• Login as root.
• Copy the archive into your home directory.
• Issue the following commands:
  • tar zxvf aprsd215.tgz
  • cd aprsd215
  • Note: The following command will also compile the source files
  • ./INSTALLPGM
  • cd /home/aprsd2
  Now make any changes you may require to welcome.txt, INIT.TNC, RESTORE.TNC and aprsd.conf to reflect your call sign, location and TNC paramters.
  Note: The install program will not overwrite these if they already exist.

COMMAND LINE PARAMETERS

While running, once each minute this server will emit a status message to the console. Also, it tells you each time it sends out a packet and to how many users. It also shows you what it's sending to the TNC. One field in the status message is aprsString Objs. This is a debugging tool to help find memory leaks. It should be no more than 1 or 2 higher than the History items field. Sometimes it will read much higher but should return to a difference of 1 or 2 within a minute or so.

Ctrl-C or "q" will shut down the server in an orderly manner and save the current history list (last 30 mins of select received data) to disk.

SERVER CONFIGURATION FILE

COM PORT CONFIGURATION

Be sure the device ( dev/ttyS* ) has the proper read/write permissions or the server will not be able to access it.

Root can set the serial port so it can be written to by anyone with the following command:

chmod ugo+w /dev/ttyS0

NOTE: If you don't define a device for the com port in the aprsd.conf file all TNC related functions in the server are disabled.

SHUTTING DOWN THE SERVER WHEN RUNNING AS A PROGRAM

Ctrl-\ shuts down without saving anything.

When running as a daemon you can shut it down when logged on as root by issuing this command: "service aprsd.init stop".

REMOTE TNC SYSOP ACCESS on Port 14500

tnc::102:root,wa4dsy,bozo

In this example users root,wa4dsy and bozo are assigned to the tnc group.

After you have logged on, everything you type goes to the TNC and all TNC output data goes only to you. The TNC is effectivly disconnected from all other internet users. Hit control-C to get the TNC into command mode.

To exit remote TNC access hit the key. You may also need to hit if your Telnet program sends data a line at a time. Some Telnet programs can be configured for character at a time mode. Check your documentation for details. As of version 2.1.5 aprsd should put your telnet client into character-at-a-time mode automatically.

REMEMBER TO ENTER THE TNC "K" COMMAND BEFORE YOU EXIT.

To disconnect hit ctrl-D .

LOG FILES

/home/aprsd2/aprsd.log	User logons and logoffs and some system activity msgs.

/home/aprsd2/thirdparty.log	 3rd party messages sent on RF.

/home/aprsd2/udp.log	Record of data entering from the UDP port.

/home/aprsd2/rf.log     Record our own packets heard on RF by the TNC. 
                        (After being digipeated)
                        
/home/aprsd2/loop.log   Packets that were NOT flaged as duplicates and
                        rejected by the LOOP detector.

/home/aprsd2/reject.log Packets rejected by aprsd excluding dups.

You can also use the "less" program to view it. After entering "less /home/aprsd2/aprsd.log" you type "F" to follow it in real time. Type ctrl-C to exit "F" mode.

All 3rd party station to station messages relayed from the Internet to RF are logged in /home/aprsd2/thirdparty.log

3rd party formatted packets received by the TNC with "TCPIP" in the 3rd party path will never be sent anywhere.

Data from the UDP port are logged in /home/aprsd2/udp.log .

All data heard on RF with the "MYCALL" callsign with be logged in rf.log . This feature lets you see what you have sent out on RF if you are being digipeated by someone else.

To keep the log files from getting too large they need to be rotated on a regular basis. Add the following to your /etc/logrotate.conf file. Log files will be rotated daily or weekly and the oldest deleted after 4 rotations. Feel free to modify the schedule to suit your needs.

/home/aprsd2/aprsd.log {
        weekly
        rotate 4
}

/home/aprsd2/thirdparty.log {
        daily
        rotate 4
}
/home/aprsd2/udp.log {
        daily
        rotate 4
}
/home/aprsd2/rf.log {
        daily
        rotate 4
}

/home/aprsd2/loop.log {
        daily
        rotate 4
}

/home/aprsd2/reject.log {
        daily
        rotate 2
}

STATION TO STATION 3RD PARTY MESSAGES

It came from a logged on verified registered user.

and

The originator was not seen on the TNC RF data stream in the past 30 minutes.

and

The destination HAS been seen on the TNC RF data stream in the past 30 minutes and doesn't have "GATE*" in his path and has been repeated less than 3 times.

and

The line "rf-allow yes" is in the /home/aprsd2/aprsd.conf file.

Version 2.0.8 and later allows you to define up to 64 message destination call signs or aliases which will always be gated to RF if "rf-allow yes" has been defined. See the example aprsd.conf file for an example of how to use the "msgdest2rf" command to enable this feature. For each 3rd party messge delivered to RF the latest position report packet of the originating station will also be sent after reformating the path in 3rd party format. The program pulls the posit from the history list if it's in there.

eg:

KE6DJZ>AP0917,KB6TLJ-5,RELAY,WIDE:=3415.99N/11844.34WyAPRS+SA

becomes:

}KE6DJZ>AP0917,TCPIP,WA4DSY*:=3415.99N/11844.34WyAPRS+SA

(assuming "MyCall" is WA4DSY )

During a series of messages the position packet will only be sent with a message every 10 minutes unless the station emits and new one.

This server will NOT igate a 3rd party _reformatted_ message from RF to the Internet which has been previously on the Internet. ie: has TCPIP in the 3rd party path. 3rd party packets without TCPIP in the 3rd party path will be converted to normal packets and processed in the usual way.

Users of unregisterd client programs can send their own station-to-station messages to other Internet users. These messages will not go out on the TNC RF channel and the path will be modified (TCPIP is changed to TCPXX*) so other hubs will know not to send these messages out on their RF channels. Unregistered users cannot Igate packets other than their own. In other words, the ax25 source call in their packets must match their logon call and "TCPIP" must be in the path. (TCPIP* or TCPXX* will not work either)

eg: assume N0CALL is unregistered and attempts to send the following into the server.

N0CALL>APRS,TCPIP:>TESTING
This will be converted to N0CALL>APRS,TCPXX*:>TESTING and gated to other users (but not to RF!)

However...
W4ZZZ>APRS,TCPIP:>TESTING
or
N0CALL>APRS,TCPIP*:>TESTING
will be deleted and not sent anywhere.
Telnet users must provide a user name or call sign before any of their data can be relayed to the internet. They need to enter "user callsign pass -1" so the server will accept the data. The ax25 FROM call in packets they send must match the call sign they loggon with. If they provide a valid password full priviliges are granted since they used the keyboard to emulate a client program logon string. (Not that anyone would want to do this except for testing)

This server will also accept valid user/password combinations for the Linux system it is running on. These users must be in the aprs group. This group can be added by editing the /etc/group file.

Note:

This program trusts other versions of itself and APRServe to flag the paths of data from unregistered Internet users with "TCPXX*". Station to station messages flagged this way will not be sent out on RF. The IGATE commands in the aprsd.conf file should specify a remote host port which is secure. For IGATES it must be a port which doesn't echo any Internet user data, only TNC data. Full function servers such as APRServe and this version (2.x.x) of aprsd will change TCPIP* to TCPXX* in the paths of unregistered users on all ports.

Users of the current java APRS applet don't log in at all and are granted read-only access

MESSAGE ACKS (New in 2.0.7)

USER VALIDATION

If the users APRS name and pass code aren't valid the validate module tries the Linux pass word validator for the "aprs" group. If that also fails it waits 10 seconds then returns the bad news to aprsd which notifies the user.

NOTE: aprsd must be run as root for the Linux password validator to work. However, the APRS user and passwords (from Mac/WinAPRS users) will be properly tested regardless of what user is running aprsd if "aprsPass yes" is in the aprsd.conf file.

The logon format:

user pass vers

eg: user N0CALL pass 00001 vers MacAPRS 3.0
might be sent by a MacAPRS user.
As pass code of -1 means you are an unregistered user, not a hacker trying out an bogus password.

You can telent to a port and enter the following, assuming your Linux user name is bozo and you password is xyzzy and you are part of the aprs group as defined in the /etc/group file.

user bozo pass xyzzy

To monitor some server status data you can enter:

user bozo pass xyzzy vers monitor

The aprs data stream is turned off and "Monitor Mode" is entered. Once a minute the server will send a status message to you.

Once you have logged on, ctrl-D will not cause a disconnect. You have to use your Telnet escape key then do a quit. I had to do this to prevent inadvertant disconnects due to possible spurious control codes in some users data.

KEEPING ABUSERS OUT OF THE SYSTEM (New in 2.1.0)

user.deny example:

W4EVIL L   <--- Prevents sending of packets into the server or RF
W4SOB R    <--- Prevents any of his packets from getting on RF
		even if they came from another igate.


NOTE: This file is read every time aprsd needs to check users
so you will NOT need to restart the server when you change it.

Full time gating of selected stations from Internet to RF

There are three "modes" of doing this. The most permissive allows all packets from a selected station to be sent to RF in real time. The second mode only allows position report packets to be sent on RF every 14.9 minutes. This puts much less strain on the RF network and is the recommended mode.

The third mode which was new in version 2.0.8 gates 3rd party station to station messages to RF full time if the DESTINATION call sign or alias is defined in the aprsd.conf file after the msgdest2rf keyword.

You select the stations by entering them in the /home/aprsd2/aprsd.conf file. Up to 64 stations can be defined. Several can be put on each line. The server must be restarted before any changes to aprsd.conf take effect.

In version 2.1.5 the "*" wild card character is supported. Characters past the "*" will be ignored in the compare operation. For example W7LUS* would allow all W7LUS ssids to match. Examples:

These stations posits are sent to RF every 15 minutes: 
posit2rf K4HG-8 N4NEQ-9 
posit2rf W7LUS-14

All packets from this station are gated to RF full time.
gate2rf N0CLU-9

Any call with the first 5 characters matching W7LUS will
be gated to RF full time. eg: W7LUS-1 and W7LUS-13.
gate2rf W7LUS*




This allows any message addressed to SCOUTS, KIDS or CQGA to go to
RF even though these "call signs" were not heard locally.
msgdest2rf SCOUTS KIDS CQGA

NOGATE and RFONLY

Version 2.1.5 adds support for NOGATE and RFONLY in the path. Any packet from any source with "NOGATE" or "RFONLY" in its path will be discarded.

MIC_E PACKET TRANSLATION

The unconverted raw Mic_E packets from the local TNC can be observed by telneting to port 14580.

AEA to TAPR conversion

Packet Source path insertions

The first added path elemement is a three letter code indicating data protocol and info about the source of the packet. This code can be expanded in the future as needed.

The first character is always "q". The second character is a protocol identifier for the data payload. Currently only A=APRS is defined. The third character is a code that identifies the source of the packet. The possible codes are C, X, R, , r, S, U, I, Z. They are defined as follows:

Code          Source

C        Validated Client (User). Packet had no q construct.
X        Unvalidated Client
R        RF packet from local TNC or converted from CALLSIGN,I construct
r        Same as above but received indirectly via another server.
S        Server or Hub
U        UDP port on aprsd server
I        Internal status message from aprsd server and Trace Packet
Z        Zero hops and Internal, do not repeat this packet

Following the qAc path element is the identifier callsign:

Source            Identifier

C or X User   Users Login Call sign. 
S APRS Hub    IP address of distant server in HEX. This is the "Hex IP Alias".
I Internal    Server callsign.  (ServerCall in aprsd.conf)
R TNC         IGATE callsign or Callsign preceeding the "I" if converted from CALLSIGN,I .
r             Callsign preceeding the "I"
U UDP         Server callsign.
Z             Server callsign.

Here are some examples.
Assuming MyCall is WA4DSY, ServerCall is aprsdATL, Logged on user is WA4ABC, we are connected to and receiving data from first.aprs.net and the path does NOT already have an qAc, we add:

qAC,WA4ABC     from validated internet Client WA4ABC
qAX,WA4ABC     from unvalidated client
qAR,WA4DSY    from local TNC (RF) 
qAR,W4ABC      from logged on client "W4ABC" and converted from W4ABC,I.
qAr,N4ZZ       from a server and converted from N4ZZ,I format.
qAS,C6581502  from Server/Hub third.aprs.net (IP address = 198.88.21.2) (no q and no I )
qAU,aprsdATL   from UDP port
qAI,aprsdATL   from Internal source (server beacon, etc). Packet will be traced.
qAZ,aprsdATL   from Internal source that should not be repeated (server status messages)

If a packet comes in from directly connected client "MYCALL" and already has a MYCALL,I on the end of the path aprsd 2.1.5 swaps the position of the "I" and preceeding callsign and changes the I to qAR. WA4DSY>APRS,WA4ABC,I:data becomes WA4DSY>APRS,qAR,WA4ABC:data .

If a packet is received from another server and has MYCALL,I in the path, the packet is converted to the qAr,MYCALL format.

The path will be either zero or 2 elements longer than the original.

If trace is enabled by setting "TRACE YES" in aprsd.conf, all packets passing through aprsd will have the servers call appended to the end of the AX25 path.

Example:

trust 198.162.50.5 

Example:

trust 198.162.50.0 255.255.255.240 

 

This goes to the TNC: WA4DSY>TNC:Data for TNC here
This goes to TCPIP: WA4DSY>APRS:Data for the Internet

The complete string including the path goes out on the Internet.

See the file "udp_example" for a sample perl script.

RESPONDING TO QUERIES

WA4DSY>APRS:?IGATE? 

aprsdATL>APD215,TCPIP*:<IGATE,MSG_CNT=11,LOC_CNT=59,CALL=WA4DSY,
LOCATION=Atlanta_GA,HOST=wa4dsy.net,IP=216.27.174.144,
EMAIL=sysop@myisp.com,VERS=aprsd 2.1.5

Most of the data comes from the aprsd.conf file.

• MSG_CNT=11 is number of packets sent to RF
• LOC_CNT=59 is number of items defined as "LOCAL" in the history buffer
• CALL=WA4DSY is from mycall from INIT.TNC
• LOCATION=Atlanta_GA is from mylocation
• HOST=wa4dsy.net is host name obtained from Linux OS
• IP=216.27.174.144 is IP address from Linux OS
• EMAIL=sysop@myisp.com is from myemail
• VERS=aprsd 2.1.5 is internal version number string.

Note that directed queries are no longer supported because of problems with RF flooding.

Java Applet

APRS passcode calculator (new in 2.1.1)

./aprspass N0CALL
APRS passcode for N0CALL = 12345

igate second.aprs.net 23 N0CALL 12345

Monitoring system status with a web browser (new in 2.1.2)