



Chapter  1



User  Manual



1.1    Introduction


This is the user manual for the RSPF daemon. With this you will hopefully
be able to setup and understand what the daemon is doing.
   A daemon is like a server which is used by the Linux operating system
to talk to some other system. They usually have something to do with net-
working but don't have to be. This daemon implements the Radio Shortest
Path First (RSPF) protocol version 2.2, as specified in Fred Goldstein's
Specification.
   The implementation of RSPF v2.2 is the result of my Computer Systems
Engineering Thesis or final year project.  It has taken approximately 15
weeks to code and test. I expect that there will be still some bugs left and
would welcome any comments from users.



1.2    Features


This program has many more features that the RSPF in NOS. Some of
these are mentioned in the specification, some are interpretations of it and
others are extensions. A brief list of the features are;

   * Runs as a daemon runs on a Linux platform using the AX.25 code in
     kernel.

   * Manipulates the Linux routing table

   * A small client program using UDP to interrogate daemon

   * Forwards any new routing bulletin information onto all ports


                             1




2                                 CHAPTER 1.  USER MANUAL



   * If a received routing bulletin is older than one we hold, we send our
     newer information onto the port we heard the old one.

   * When a new RSPF router is discovered, send full routing bulletin.

   * Uses node groups to reduce routing traffic

   * Implements different horizons for different types of links

   * Many more configurable values using a configuration file.

   * Reporting of errors or warnings to syslog

   * Adheres to RSPF v2.2 specification as much as possible.

   * Code is licensed under GNU General Public License

   * Tentative adjacencies are now ping-ed on the correct port, not the
     default one.



1.3    Compatibility between 2.1 and 2.2


When making the program, I have tried to make sure that it will understand
RSPF v2.1 packets. To this end, I have tested the program with TNOS 1.11
which runs the v2.1 code, as do almost all xNOS's.
   There is not much difference between the 2.1 and 2.2 packets. Unfor-
tunately a v2.1 router will ignore any packet that has a v2.2 identification.
You can optionally set the version number used by the program to 2.1 so
it is not ignored.



1.4    Installation


To install the program you first will need the tgz (tar and gzip'ed) file.
This is available from ftp.ucsd.edu /hamradio/packet/tcpip/linux or from
sunsite.unc.edu /pub/Linux/apps/ham. Of course, it should be available
from any site that mirrors either of these.
   Untar the file in a directory such as /usr/src with
   tar xvfz rspfd-1.0.tgz.
   You should then have a directory called rspfd-1.0 with some files in it.
   Change directory to rspfd-1.0 and read the README.  That file will
hold any last-minute information about the program, until I can update
this file. You now have a choice of either using the files I have compiled or
using your own.




1.5.  CONFIGURATION FILE                                  3



   To use my files just type 'make install'.
   To recompile the program, type 'make' and then 'make install'.
   Note, you'll have to be root before you install the program.
   This will then put the files in /usr/local/etc. If you want to put these
files somewhere else then you will have to change the Makefile and change
the CONFIG_FILE entry in src/rspfd.h.
   Next is to change the configuration file to suit your site. The parameters
are explained in the next section. The most important parameters to change
are the interface ones.
   In addition, it is unlikely that your system will know what the RSPF
protocol is, so you will have to edit your /etc/protocols file, add a line that
has rspf 73 RSPF #Radio Shortest Path First.
   This will mean that it knows about the protocol called RSPF. If you
do not do this, the program won't be able to transmit and will give an
unknown protocol error.
   You will also have to ensure you have routes for the broadcast addresses.
This is a bit of a pain, but I cannot see any simple way around it. Make
sure you use the -host flag when setting the route.



1.5    Configuration File


RSPFd uses a configuration file to set a lot of its parameters. It also uses
this file to work out which interfaces to use. The default pathname for the
file is /usr/local/etc/rspfd.cf.
   The following parameters are used in the configuration file. Note that
they all must be in lowercase and of the format <option>=<value>.

#  Any line beginning with the hash (#) symbol is teated as a comment.

rrhtimer Number of seconds between Router-Router Hellos (RRH).

sustimeout An adjacency becomes suspect if we have not heard from it
     in this amount of time in seconds.

pingtimer This is the amount of time the daemon waits after sending a
     ping to a suspect or tentative adjacency before sending another one.

suspings The number of pings attempted on a tentative or suspect adja-
     cency.

reasmtimeout The number of seconds to wait after receiving a routing
     bulletin fragment before considering the following fragment has been
     lost.




4                                 CHAPTER 1.  USER MANUAL



bulltimer Number of seconds between sending full routing bulletins (not
     including bulletins that are send due to new routers).


bulltimeout Number of seconds before a routing bulletin's sequence num-
     ber is considered invalid. This is so when a router crashes and forgets
     its sequence number you don't ignore it's routing updates as old for
     a long time.


linkhorizon The horizon that is given to adjacent routers. This should be
     a large value such as 32 to be sent far.


grouphorizon The horizon given to node group advertise-ments.  This
     should be similar to link horizon.


localhorizonThe horizon given to adjacent non-routers that are in one
     of the local node groups. This should be small as it is only to resolve
     which router out of a few will service specific nodes in the node group.


portablehorizon The horizon given to adjacent non-routers that are not
     in a node-group. This should be similar to link horizon.


   In addition, there is a parameter to specify which interfaces to use. The
format of these lines are 'rspfiface=<dev> <cost>'. Dev is the name of
the device, same as what you would use in ifconfig. Cost is the cost of all
adjacencies on that interface. This value should be ideally determined by
the network as a whole and agreed upon.
   One way to work out a good set of values to use is this way.  255 is
infinity, so you think of a set of links that for all intents and purposes are
unreachable. Perhaps 4 jumps at 1200bd could be considered to be unlikely
to succeed. So that means you could make the cost of a 1200bd port be 64
(approximately 255/4). For other speeds you can either do a similar thing
or some other way. We generally consider a port of double speed should
have half the cost, so use 16 for 4800 and 8 for 9600. All Ethernet, SLIP
links etc are considered to have cost 1. Whatever method you use is up to
you. Remember that 255 is 'infinity' and lower cost means it is a 'better'
interface.



1.6    Starting RSPFd


To start the RSPF daemon, it is just a matter of typing 'rspfd' at the
shell prompt. I would suggest that you put a line in your /etc/rc.local or
/etc/rc.net to start the daemon up every time you boot.




1.7.  INTERACTION OF V2.2 WITH V2.1                        5



   There will be a line in the syslog (usually /usr/adm/messages) stating
when the program has started. Any errors that the daemon gets will also
be put into the syslog.
   The program will automatically execute a fork() routine and clean stuff
up so that it behaves like a proper daemon should.  In the production
version, there should be no output at all. For the testing versions, there is
a lot of output, I generally redirect output to another tty.



1.7    Interaction of v2.2 with v2.1


There are some slight but significant differences with RSPF v2.2 to RSPF
v2.1. The daemon will correctly (as far as I can tell) decode v2.1 packets
and add them to the link-state table.  However when sending out newer
link-state information it will be in v2.2 format.
   When running alpha tests, it was discovered that something in the rout-
ing update envelopes would make NOS systems crash if you dummied the
newer packets with a v2.1 version number. v2.1 does not handle the hori-
zons correctly. A horizon is a property of a link-state, not a link (or in-
terface) as different adjacencies on the same interface can have different
horizons.
   For this reason, do not dummy the version number of the outgoing
RSPF packets to v2.1 so that other systems can receive them. Bad things
will happen to those systems, and their link-state table will get some pretty
weird entries.
   There also appears to be a problem in v2.1 with handling partial routing
updates. I cannot nail down the behavior, but it seems that it treats partial
updates as full updates.



1.8    RSPF Client


As the daemon itself does not have very much to say, there may be a need
to work out what the daemon has in its tables. To do this, there is a RSPF
client which queries the daemon using UDP. The port for this is 9006 which
offers no significance (other than the first four digits of my student number)
and can be changed.
   The client will default to the loopback host, but can be told to go to a
different port or host by starting it with rspfc <host> <port>.
   The following commands can be used, all are in upper case.

ADJS  Gives a list of the current adjacencies to this router. Adjacencies
     that have sent a RRH have a sequence number and Lastheard entry.




6                                 CHAPTER 1.  USER MANUAL



     This is last time the station heard a RRH, not last time the remote
     station was heard.

HELO   Just returns back the version string of the daemon.

HELP   Gives a list of the available commands.

IFCS  Shows the interfaces that RSPF has been configured, the cost of
     that interface and how many adjacencies we have for it.

LNKS   Displays the link-state table that is used by the SPF algorithm.
     Most fields are obvious but the sequence number is the number of the
     bulletin that sent that link-state. All sequence numbers should be the
     same for the same source address, except for the local router.

ROUT   The routes that we have added to the kernel routing table. This
     should generally agree with the entries in the routing table with the
     D (Dynamic) flag set.

RTRS   This will show you the routers that we have heard bulletins from.
     This means they do not have to adjacent but just we have received a
     bulletin.

STAT   Dumps a whole lot of statistics about the daemon. Mostly used for
     debugging purposes.

   The server will also reply back with the hostname of the host it sits on,
to make sure you're talking to the correct one.
   There is currently no security on this information. Anyone with a client
can interrogate any server.  This was done so that people can debug a
network, if the problem is not on their router. If there is enough demand, I
can put some simple security in, but as the information cannot be changed,
I cannot see any reason for it.



1.9    How it works


The RSPF daemon is a reasonably complex program, so I cannot really go
into details. If you want to know, read the RSPF v2.2 spec and look at the
source code. I can, however, give an overview of how it works.



1.9.1   Adjacencies

One thing a new router has to do is meet its neighbors. It can do this in
two ways.




1.9.  HOW IT WORKS                                        7



   The first is by hearing a RSPF packet from someone.  It will decode
this information and then make the adjacency tentative. Next is to hear an
ARP request or reply. It uses the sender's address in both cases to make
a tentative adjacency. In both cases the adjacency is tentative only if we
don't already have it.  The system will attempt to ping the adjacency a
number of times. If it replies, it is a OK adjacency, if not it is removed.
   One of the problems with pinging tentative adjacencies is that the rout-
ing table shouldn't already have this adjacency.  What happens is if the
table doesn't have an entry for the adjacency, it adds one, pings, then
removes it. This allows only the daemon to try to reach an adjacency.
   If an OK adjacency is not heard from a certain amount of time, it is
marked as suspect and attempted to be pinged.  If it doesn't reply, it is
removed and a partial routing update is sent, notifying others that that
link-state has gone.
   At regular intervals, the daemon sends RRH's and full routing updates.
These can be configured in the configuration file.



1.9.2   Routing Bulletins

On reception of a routing envelope fragment, the daemon will go through
all the routing bulletins.  Received routing bulletins that have the same
sequence number are discarded.  Ones with higher ones update the link-
state table and are forwarded onto all interfaces. Ones with lower numbers
are rejected and a bulletin for that reporting router is sent on the interface.
   Something that is different to the old version is the use of sequence
numbers. What happens is that if you receive a routing bulletin originated
from you and it has a higher sequence number, you increment your internal
counters to that number. This is so that stations that crash can get back
to the correct sequence number.
   Also note that sequence numbers are NOT modulus.  In other words
0xffff (-1) is bigger than 1. What happens is that if a station reaches 0xffff
in the sequence counter, it sends no more routing updates until a certain
time, when all the nodes have 'forgotten' it. It then starts up again with
sequence number 1.
   Sequence number 0 means a poll.
