The Router Discovery Client and Server support the state trace flag, which traces various protocol occurrences.

The Router Discovery Client and Server do not directly support any packet tracing options, tracing of router discovery packets is enabled with the ICMP statement.

A.16 The Kernel Statement

While the kernel interface is not technically a routing protocol, it has many of the characteristics of one, and GATED handles it similarly to one. The routes GATED chooses to install in the kernel forwarding table are those that will actually be used by the kernel to forward packets.

The add, delete and change operations GATED must use to update the typical kernel forwarding table take a non-trivial amount of time. This does not present a problem for older routing protocols (RIP, EGP), which are not particularly time critical and do not easily handle very large numbers of routes anyway. The newer routing protocols (OSPF, BGP) have stricter timing requirements and are often used to process many more routes. The speed of the kernel interface becomes critical when these protocols are used.

To prevent GATED from locking up for significant periods of time installing large numbers of routes (up to a minute or more has been observed on real networks), the processing of these routes is now done in batches. The size of these batches may be controlled by the tuning parameters described below, but normally the default parameters will provide the proper functionality.

During normal shutdown processing, GATED normally deletes all the routes it has installed in the kernel forwarding table, except for those marked with retain. Optionally, GATED can leave all routes in the kernel forwarding table by not deleting any routes. In this case changes will be made to insure that routes with a retain indication are installed in the table. This is useful on systems with large numbers of routes as it prevents the need to re-install the routes when GATED restarts. This can greatly reduce the time it takes to recover from a restart.

A.16.1 Forwarding Tables and Routing Tables

The table in the kernel that controls the forwarding of packets is a forwarding table, also known as a forwarding information base, or FIB. The table that GATED uses internally to store routing information it learns from routing protocols is a routing table, also known as a routing information base, or RIB. The routing table is used to collect and store routes from various protocols. For each unique combination of network and mask an active route is chosen, this route will be the one with the best (numerically smallest) preference. All the active routes are installed in the kernel forwarding table. The entries in this table are what the kernel actually uses to forward packets.

A.16.2 Updating the Forwarding Table

There are two main methods of updating the kernel FIB, the ioctl() interface and the routing socket interface. Their various characteristics are described here.

A.16.2.1 Updating the Forwarding Table with the ioctl Interface

The ioctl interface to the forwarding table was introduced in BSD 4.3. This is a one-way interface; it only allows GATED to update the kernel forwarding table. It has several other limitations:

• Fixed subnet masks
  The BSD 4.3 networking code assumed that all subnets of a given network had the same subnet mask. This limitation is enforced by the kernel. The network mask is not stored in the kernel forwarding table, but determined when a packet is forwarded by searching for interfaces on the same network.
• One way interface
  GATED is able to update the kernel forwarding table, but it is not aware of other modifications of the forwarding table. GATED is able to listen to ICMP messages and guess how the kernel has updated the forwarding table with response to ICMP redirects.
• Blind updates
  GATED is not able to detect changes to the forwarding table resulting from the use of the ROUTE command. Use of the ROUTE command on systems that use the ioctl() interface is strongly discouraged while GATED is running.
• Changes not supported
  In all known implementations, there is no change operation supported, to change a route that exists in the kernel, the route must be deleted and a new one added.

The routing socket interface to the kernel forwarding table was introduced in BSD 4.3 Reno, widely distributed in BSD 4.3 Net/2 and improved in BSD 4.4. This interface is simply a socket, similar to a UDP socket, on which the kernel and GATED exchange messages. It has several advatages over the ioctl() interface:

• Variable subnet masks
  The network mask is passed to the kernel explicitly. This allows different masks to be used on subnets of the same network. It also allows routes with masks that are more general than the natural mask to be used. This is known as classless routing.
• Two way interface
  Not only is GATED able to change the kernel forwarding table with this interface, but the kernel can also report changes to the forwarding table to GATED. The most interesting of these is an indication that a redirect has modified the kernel forwarding table; this means that GATED no longer needs to monitor ICMP messages to learn about redirects. Plus, there is an indication of whether the kernel processed the redirect, GATED can safely ignore redirect messages that the kernel did not process.
• Updates visible
  Changes to the routing table by other processes, including the route command are received via the routing socket. This allows GATED to insure that the kernel forwarding table is synchronized with the routing table. Also, it allows the system administrator to perform some operations with the ROUTE command while GATED is running.
• Changes supported
  There is a functioning change message that allows routes in the kernel to be atomically changed. Some early verions of the routing socket code had bugs in the change message processing. There are compilation time and configuration time options that cause delete and add sequences to be used instead of change messages.
• Expandable
  New levels of kernel and GATED communications may be added by adding new message types.

When GATED starts up it reads the kernel forwarding table and installs corresponding routes in the routing table. These routes are called remnants and are timed out after a configured interval (which defaults to 3 minutes), or as soon as a more attractive route is learned. This allows forwarding to occur during the time it takes the routing protocols to start learning routes.

There are three main methods for reading the forwarding table from the kernel:

• Reading forwarding table with KMEM
  On many systems, especially those based on BSD 4.3, GATED must have knowledge of the kernel's data structures to read the current state of forwarding table. This method is slow and subject to error if the kernel forwarding table is updated while GATED is reading it. This can happen if the system administrator uses the ROUTE command, or an ICMP redirect message is received while GATED is starting up.
  Due to an oversight, some systems (such as OSF/1) that are based on BSD 4.3 Reno or later, do not have the getkerninfo() system call described below, which allows GATED to read routes from the kernel without knowing about kernel internal structures. On these systems it is necessary to read the kernel radix tree from kernel memory. This is even more error-prone than reading the hash based forwding table.
• Reading the forwarding table via getkerninfo or sysctl
  Besides the routing socket, BSD 4.3 Reno introduced the getkerninfo() system call. This call allows a user process (of which GATED is one) to read information from the kernel without knowledge of the kernel data structures. In the case of the forwarding table, it is returned to GATED atomically as a series of routing socket messages. This prevents the problem associated with the forwarding table changing while GATED is in the process of reading it.
  BSD 4.4 changed the getkerninfo() interface into the sysctl() interface, which takes different parameters, but otherwise functions identically.
• Reading the forwarding table via OS specific methods
  Some operating systems define their own method of reading the kernel forwarding table.

The kernel support subsystem of GATED is resposible for reading the status of the kernel's physical and protocl interfaces periodically. GATED detects changes in the interface list and notifies the protocols so they can start or stop instances or peers. The interface list is read one of two ways:

• Reading the interface list with SIOCGIFCONF
  On systems based on BSD 4.3, 4.3 Reno and 4.3 Net/2 the SIOCGIFCONF ioctl interface is used to read the kernel interface list. Using this method, a list of interfaces and some basic information about them is return by the SIOCGIFCONF call. Other information must be learned by issuing other ioctl s to learn the interface network mask, flags, MTU, metric, destination address (for point-to-point interfaces) and broadcast address (for broadcast capable interfaces).
  GATED reads rereads this list every 15 second looking for changes. When the routing socket is in use, it also rereads it whenever a messages is received indicating a change in routing configuration. Receipt of a SIGUSR2 signal also causes GATED to reread the list. This interval may be explicitly configured in the interface configuration.
• Reading the interface list with sysctl
  BSD 4.4 added the ability to read the kernel interface list via the sysctl system call. The interface status is returned atomically as a list of routing socket messages that GATED parses for the required information.
  BSD 4.4 also added routing socket messsages to report interface status changes immediately. This allows GATED to react quickly to changes in interface configuration.
  When this method is in use, GATED rereads the interface list only once a minute. It also rereads it on routing table changes indications and when a SIGUSR2 is received. This interval may be explicitly configured in the interface configuration.

Later version of the getkerninfo() and sysctl() interfaces return the interface physical addresses as part of the interface information. On most systems where this information is not returned, GATED scans the kernel physical interface list for this information for interfaces with IFFBROADCAST set, assuming that their drivers are handled the same as Ethernet drivers. On some systems, system specific interfaces are used to learn this information.

The interface physical addresses are useful for IS-IS. For IP protocols, they are not currently used, but they may be used in the future.

A.16.6 Reading Kernel Variables

At startup, GATED reads some special variables out of the kernel. This is usually done with the nlist (or kvm_nlist ) system call, but some systems use different methods.

The variables read include the status of UDP checksum creation and generation, IP forwarding and kernel version (for informational purposes). On systems where the routing table is read directly from kernel memory, the root of the hash table or radix tree routing table is read. On systems where interface physical addresses are not supplied by other means, the root of the interface list is read.

A.16.7 Special Route Flags

The later BSD based kernel support the special route flags described in the following list:

• RTF_REJECT
  Instead of forwarding a packet like a normal route, routes with RTF_REJECT cause packets to be dropped and unreachable messages to be sent to the packet originators. This flag is only valid on routes pointing at the loopback interface.
• RTF_BLACKHOLE
  Like the RTF_REJECT flag, routes with RTF_BLACKHOLE cause packets to be dropped, but unreachable messages are not sent. This flag is only valid on routes pointing at the loopback interface.
• RTF_STATIC
  When GATED starts, it reads all the routes currently in the kernel forwarding table. Besides interface routes, it usually marks everything else as a remnant from a previous run of GATED and deletes it after a few minutes. This means that routes added with the ROUTE command will not be retained after GATED has started.
  To fix this the RTF_STATIC flag was added. When the route command is used to install a route that is not an interface route it sets the RTF_STATIC flag. This signals to GATED that the specified route was added by the systems administrator and should be retained.

The kernel configuration syntax is as follows:

kernel { options [ nochange ] [ noflushatexit ] ; routes number ; flash [ limit number ] [ type interface | interior | all ] ; background [ limit number ] [ priority flash | higher | lower ] ; traceoptions trace_options ; } ;

In the kernel configuration syntax:

• options specifies kernel options. Valid options are:
  • nochange , which, on systems supporting the routing socket, ensures that changes operations will not be performed, only deletes and adds. This is useful on early versions of the routing socket code where the change operation was broken.
  • noflushatexit , which specifies that during normal shutdown processing GATED deletes all routes from the kernel forwarding table that do not have a retain indication. The noflushatexit option prevents route deletions at shutdown. Instead, routes are changed and added to make sure that all the routes marked with retain get installed.
    This is useful on systems with thousands of routes. Upon startup GATED will notice which routes are in the kernel forwarding table and not have add them back.
• routes specifies the routes number. On some systems kernel memory is at a premium. With this parameter a limit can be placed on the maximum number of routes GATED will install in the kernel. Normally GATED adds/changes/deletes routes in interface/internal/external order, for example, it queues interface routes first, followed by internal routes, followed by external routes, and processes the queue from the beginning. If a this parameter is specified and the limit is hit, GATED does two scans of the list instead. On the first scan it does deletes, and also deletes all changed routes, turning the queued changes into adds. It then rescans the list doing adds in interface/internal/external order until it hits the limit again. This will tend to favor internal routes over external routes. The default is not to limit the number of routes in the kernel forwarding table.
• flash specifies that a route has changed. The process of notifying the protocols is called a flash update. The kernel forwarding table interface is the first to be notified. Normally a maximum of 20 interface routes may be processed during one flash update. The flash command allows tuning of the following parameters:
  • limit number , which specifies the maximum number of routes which may be processed during one flash update. The default is 20. A value of -1 will cause all pending route changes of the specified type to be processed during the flash update.
  • type , which specifies the type of routes that will be processed during a flash update. Interior specifies that interior routes will also be installed (see Section A.12.1). all specifies the inclusion of exterior routes as well (see Section A.12.2). The default is interface , which specifies that only interface routes will be installed during a flash update.
    Specifying flash limit -1 all causes all routes to be installed during the flash update; this mimics the behavior of previous versions of GATED.
• background specifies that the remaining routes are processed in batches in the background, that is, when no routing protocol traffic is being received. Normally, 120 routes are installed at a time to allow other tasks to be performed and the background processing is done at lower priority than flash updates the following parameters allow tuning of these parameters:
  • limit , which specifies the number of routes which may be processed at during one batch. The default is 120.
  • priority , which specifies the priority of the processing of batches of kernel updates in relationship to the flash update processing. The default is lower , which means that flash updates are processed first. To process kernel updates at the same priority as flash updates, specify flash . To process kernel updates at a higher priority, use higher .

While the kernel interface is not technically a routing protocol, in many cases it is handled as one. You can enter the following two symbols from the command line because the code that uses them is executed before the trace file is parsed.

symbols	Symbols read from the kernel, by nlist() or similar interface.
iflist	Interface list scan. This option is useful when entered from the command line as the first interface list scan is performed before the configuration file is parsed.

The following tracing options can be specified only in the configuration file. They are not valid from the command line.

remnants	Routes read from the kernel when GATED starts.
request	Requests by GATED to Add/Delete/Change routes in the kernel forwarding table.

Use the following general option and packet-tracing options to systems that use the routing socket to exchange routing information with the kernel. They do not apply to systems that use the old BSD 4.3 ioctl() interface to the kernel.

• info
  Records informational messages received from the routing socket, such as TCP lossage, routing lookup failure, and route resolution requests. GATED does not currently do processing on these messages, just logs the information if requested.

Packet tracing options (which may be modified with detail , send , and recv ) specify the types of message and include:

• routes
  Routes exchanged with the kernel, including Add/Delete/Change messages and Add/Delete/Change messages received from other processes.
• redirect
  Redirect messages received from the kernel.
• interface
  Interface status messages received from the kernel. These are only supported on systems with networking code derived from BSD 4.4.
• other
  Other messages received from the kernel, including those mentioned in the info type above.

Static statements define the static routes used by GATED. A single static statement can specify any number of routes. The static statements occur after protocol statements and before control statements in the TCPIP$GATED.CONF file. Any number of static statements may be specified, each containing any number of static route definitions. These routes can be overridden by routes with better preference values.

There are two forms of static statements. One defines a static route through a gateway. The other is used to support multiple network addresses on a single interface.

To define a static route through a gateway, use the following syntax:

static { ( host host ) | default | ( network [ ( mask mask ) | ( masklen number ) ] ) gateway gateway_list [ interface interface_list ] [ preference preference ] [ retain ] [ reject ] [ blackhole ] [ noinstall ] ; ( network [ ( mask mask ) | ( masklen number ) ] ) interface interface [ preference preference ] [ retain ] [ reject ] [ blackhole ] [ noinstall ] ; } ; host host | default | network [ ( mask mask ) | (masklen number ) ] gateway gateway_list)

This is the most general form of the static statement. It defines a static route through one or more gateways. Static routes are installed when one or more of the gateways listed are available on directly attached interfaces. If more than one eligible gateway is available, these are limited by the number of multipath destinations supported (this compile-time parameter is currently almost always one on UNIX).

To define a static for multiple network addresses on an interface, use the following syntax:

static { ( host host ) | default | ( network [ ( mask mask ) | ( masklen number ) ] ) gateway gateway_list [ interface interface_list ] [ preference preference ] [ retain ] [ reject ] [ blackhole ] [ noinstall ] ; ( network [ ( mask mask ) | ( masklen number ) ] ) interface interface [ preference preference ] [ retain ] [ reject ] [ blackhole ] [ noinstall ] ; } ; network [ ( mask mask ) | ( masklen number ) ] interface interface

This sytax is used to define a static interface route which is used for primitive support of multiple network addresses on one interface.

The parameters for the static route statement are as follows:

• interface interface_list
  When interface is specified, gateways are only considered valid when they are on one of these interfaces. See Section A.10.1 for the description of the interface_list.
• preference preference
  Selects the preference of this static route. The preference controls how this route competes with routes from other protocols. The default preference is 60.
• retain
  Normally, GATED removes all routes except interface routes from the kernel forwarding table during a graceful shutdown. The retain option may be used to prevent specific static routes from being removed. retain insures that some routing is available when GATED is not running.
• reject
  Instead of forwarding a packet like a normal route, reject routes cause packets to be dropped and unreachable messages to be sent to the packet originators. Specifying reject causes this route to be installed as a reject route. Not all kernel forwarding engines support reject routes.
• blackhole
  A blackhole route is the same as a reject route except that unreachable messages are not supported. Specifying blackhole causes this route to be installed as a blackhole route.
• noinstall
  Normally the route with the lowest preference is installed in the kernel forwarding table and is the route exported to other protocols. When noinstall is specified on a route, it will not be installed in the kernel forwarding table when it is active, but it will still be eligible to be exported to other protocols.