RouteD
======

About
-----
RouteD is based on the FreeBSD daemon of the same name, with corresponding
man page
  http://www.freebsd.org/cgi/man.cgi?query=routed
implemented as a RISC OS module such that it can run in the background.

It listens for RIPv1, RIPv2, and Internet Router Discovery Protocol messages
on the network and will use the contents of these messages to update the
routing table used by the Internet module. This allows specific routes to be
centrally maintained and more complex network topologies than a simple single
default gateway for all traffic not addressed to the local subnet.

Starting the RouteD module
--------------------------
1. Ensure any options (see below) have been determined and put in the
   system variable
     Inet$RouteDOptions
   prior to loading the module.
2. Load the module
     *RMLoad System:Modules.Network.RouteD
   which will run in the background.

Operation
---------
When RouteD is started, it finds those directly connected interfaces
configured into the system and marked 'up'. If multiple interfaces are
present, it is assumed that the host will forward packets between networks.
The local loopback interface is not considered a valid interface in this
context.

RouteD then broadcasts a request packet on each interface and subsequently
listens continuously for request and response packets from other hosts.
Notification of the arrival of these packets is performed in the background,
via RISC OS events.

When a request packet is received, RouteD formulates a reply based on the
information maintained in its internal tables. The response packet generated
contains a list of known routes, each marked with a hop count metric (a count
of 16, or greater, is considered 'infinite'). The metric associated with each
route returned provides a metric relative to the sender.

Response packets received by RouteD are used to update the routing tables if
one of the following conditions is satisfied:

* No routing table entry exists for the destination network or host, and the
  metric indicates the destination is reachable (ie the hop count is not
  infinite).
* The source host of the packet is the same as the router in the existing
  routing table entry. That is, updated information is being received from
  the very internetwork router through which packets for the destination are
  being routed.
* The existing entry in the routing table has not been updated for some time
  (defined to be 90 seconds) and the route is at least as cost-effective as
  the current route.
* The new route describes a shorter route to the destination than the one
  currently stored in the routing tables. (The metric of the new route is
  compared against the one stored in the table to decide this.)

When an update is applied, RouteD records the change in its internal tables
and updates the Internet module routing table. The change is reflected in
the next response packet sent.

In addition to processing incoming packets, RouteD also periodically checks
the routing table entries. If an entry has not been updated for 3 minutes,
the entry's metric is set to infinity and marked for deletion. Deletions are
delayed an additional 60 seconds to insure the invalidation is propagated
throughout the local internet.

Hosts acting as internetwork routers gratuitously broadcast their routing
tables every 30 seconds to all directly connected networks. The normal
routing tables are bypassed when sending gratuitous responses. The reception
of responses on each network is used to determine that the network and
interface are functioning correctly. If no response is received on an
interface, another route may be chosen to route around the interface, or the
route may be dropped if no alternative is available.

Inet$RouteDOptions
------------------
RouteD supports several option flags, passed in this system variable. Not all
of the flags that the FreeBSD daemon support are available on RISC OS.

  s  Supplying this option forces RouteD to supply routing information whether
     it is acting as an internetwork router or not. This is the default if
     multiple network interfaces are configured for TCP/IP.
  q  This is the opposite of the 's' option, and is the default when only
     one network interface is configured for TCP/IP.
  g  This flag is used on internetwork routers to offer a route to the
     'default' destination. This is typically used on a gateway to the
     Internet, or on a gateway that uses another routing protocol whose routes
     are not reported to other local routers.
  h  Host or point-to-point interfaces are not advertised. This is useful on
     a gateway that has a point-to-point connection such as SLIP.
  m  Do advertise host or point-to-point interfaces. This is useful on multi
     homed machines, and overrides the 'q' option.
  A  Don't ignore RIPv2 authentication, if this machine doesn't itself care
     about RIPv2 authentication. This option is only provided for compliance
     with RFC1723, and should not be used.

The default option is used if Inet$RouteDOptions contains the text DEFAULT.

  *Set Inet$RouteDOptions [s|q][g][h][m][A][DEFAULT]

Gateways
--------
In addition to the facilities described above, RouteD supports the notion of
'distant' passive and active gateways. When RouteD is started up, it reads the
file InetDBase:gateways (if present) to find information about such gateways.

Gateways specified in this manner should be marked passive if they are not
expected to exchange routing information, while gateways marked active should
be willing to exchange routing information (ie. they should have a RouteD
process running on the machine). Passive gateways are maintained in the
routing tables forever and information regarding their existence is included
in any routing information transmitted.

Active gateways are treated equally to network interfaces. Routing information
is distributed to the gateway and if no routing information is received for a
period of time, the associated route is deleted. External gateways are also
passive, but are not placed in the routing table nor are they included in
routing updates. The function of external entries is to inform RouteD that
another routing process will install such a route, and that alternate routes
to that destination should not be installed. Such entries are only required
when both routers may learn of routes to the same destination.

The gateways database
---------------------
The InetDBase:gateways file is comprised of a series of lines, each in the
following format:

  net|host <dest> gateway <gw> metric <hops> passive|active|external

* The net or host keyword indicates if the route is to a network or specific
  host. It is followed by a <dest> parameter gives an Internet host or network
  specified either by name (which must be present in the respective host or
  network name data base InetDBase:hosts or by address (using the standard
  Internet dot notation).
* The <gw> parameter gives the name or address of the next-hop gateway to
  which packets should be forwarded.
* The metric parameter is a count giving the number of hops to the destination.
* One of the keywords passive, active or external indicates if the gateway
  should be treated as passive or active (as described above), or whether the
  gateway is external to the scope of the RouteD protocol.

Empty lines, and lines beginning with a '#' character are ignored.

Example
  # How to get to 10.1.2.3
  host 10.1.2.3 gateway 10.0.0.128 metric 2 passive

Commands
--------
                                                                 *RouteDTraceOn
  Turn on tracing by the RouteD module

Syntax
  *RoutedTraceOn <level> [filename]

Parameters

  level
    level (1-4) of trace required, where 1 is the lowest level and 4 the highest
  filename
    a valid pathname specifying the file to which to output trace, if no
    file is given the trace messages will be printed on screen

Use
  *RouteDTraceOn turns on tracing by the RouteD module. The output may be
  written either on the standard output or into the given logging file (which
  remains open until *RouteDTraceOff is invoked).
  
  Most of the information displayed is runic in nature, and not
  internationalised. It is presented mainly as an aid to trouble-shooting, 
  should you require it.

Example

  *RouteDTraceOn 2 SCSI::HardDisc4.$.TraceOut

                                                                *RouteDTraceOff
  Turn off tracing by the RouteD module

Syntax
  *RoutedTraceOff

Use
  *RouteDTraceOff turns off tracing by the RouteD module.

Example
  *RouteDTraceOff
