%
% x-kernel v3.3
%
% Copyright (c) 1996,1993,1991,1990  Arizona Board of Regents
%

\subsection {The {\var router} Entry}\label{router_entry}

A {\var router} entry indicates a type of router, gives its routing
table, and sets the number of router buffers.  Routers can output
several different kinds of trace information, and the type and amount
of tracing is specified here too.  The format of the entry is:

\begin{verbatim}
router <type> <name>;
  rtable = <destination> <next hop>, <destination> <next hop>,... ;
  args = <arg>, <arg>, ... ;
\end{verbatim}

\noindent
The {\var router} line specifies the type of network. Two types of routers
are supported at present: {\var FCFS} and {\var RED}.  The router's name must match that
used in the {\var net} entry.

The {\var rtable} line specifies the routing table.  The {\var
destination} is the network portion of a packet's IP address and the
{\var next hop} is where the router should send a packet with that
network destination.  If the next hop has no host address, then it is
assumed that the router is directly connected to the destination
network and it should send the packet to the final destination host.
Note that the entries specified on the {\var rtable} line are scanned
{\it in order} by the simulator.  In other words, if multiple {\var
next hops} are present for a particular destination, the router sends
the packet to the first one listed.  This fact becomes important when
using shortcuts to set up a routing table, as described below.

The simulator interprets a few IP addresses in a nonstandard way. This
is done to make it easier to configure a large internetwork.  If IP
addresses are chosen so that networks with similar IP addresses are
near each other in an internetwork, then routing tables can be
specified quickly and easily by using the special addresses as
``destinations'' in the routing table.  Given a packet with
destination IP address of the form {\bf a.b.c.d}, the following IP
addresses have special meaning when used in the {\var destination}
field:

\begin{itemize}

\item 0.0.0.0: Route packet to the specified next hop, regardless of
destination.  This allows the specification of a default route.

\item 1.0.$x$.0: If ${\bf c} \le x$, route packet to specified next hop.

\item 2.0.$x$.0: If ${\bf c} \ge x$, route packet to specified next hop.

\item 3.$x$.$y$.0: If $x \le {\bf c} \le y$, route packet to specified next hop.

\end{itemize}

The {\bf c} in all of the above relations refers to the third
component in the packet's destination address, {\bf a.b.c.d}.
Clearly, these special addresses are most useful if all networks in a
simulation are uniquely identified by their {\bf c} components.

For example, consider the following entry in a routing table:

\begin{verbatim}
    router FCFS r1;
      rtable = 3.1.5.0 192.1.10.100, 0.0.0.0 192.1.20.100;
\end{verbatim}

Packets with IP destination address of the form {\bf a.b.c.d} will be
routed to 192.1.10.100 if $1 \le {\bf c} \le 5$.  Therefore, a packet
destined to 192.12.3.79 will be sent there, but 192.12.6.3 will not.
The latter packet falls through to the last entry, which routes that
packet to 192.1.20.100.

The {\var args} line of the {\var router} entry contains parameters
for the router. These parameters set the number of router buffers and
select trace options.  Parameters for the FCFS router are listed in
Section~\ref{FCFS}.  A syntactic point to be aware of is that no
spaces should be included anywhere between the argument and its value;
e.g., {\var buf=30}.

\subsubsection {First Come First Serve ({\var FCFS})}\label{FCFS}

A {\var FCFS} router queues and forwards packets in the order in which
they arrive.  Each output port of the router has a queue associated
with it.  These queues are of limited size, and packets routed to an
output port while its queue is full are dropped by the router.

The following arguments can be used with the router:

\begin{verbatim}
buf=<integer>
\end{verbatim}

Sets the number of buffers in the router's queue.  The router will be
able to queue up to this number of messages; any additional messages
will be dropped.  The default is 0, so this parameter must be
specified.

\begin{verbatim}
shortTrace=<integer>[:<integer>]
\end{verbatim}

Specifies the lowest level of trace detail, mainly information about
losses. The integer arguments specify the quantity of resources
dedicated to saving the trace information.  The first integer argument
specifies the size, in trace entries (about 8 bytes each), of the
circular buffer used to hold trace information in memory.  If the
optional {\var :<integer>} portion of the argument is {\it not}
specified, this number also represents the maximum size of the trace
file. Thus, an argument of {\var 10000} specifies a buffer size of
10,000 entries, and the trace file will contain no more than this
number of entries. If the second integer argument is given, it
specifies the maximum number of memory buffers that the disk file may
contain.  When this argument is specified, then once the circular
buffer is full, the buffer is dumped to the trace file before its
traces are overwritten.  Thus, {\var 10000:3} specifies a buffer size
of 10,000 entries and a trace file of up to 30,000 entries.  Be aware
that the trace file also operates as a circular buffer, and if more
than the maximum number of trace entries are generated, the earliest
will be overwritten.  In general, it is recommended that the file be
bigger than the internal trace buffer. Also note that niether for the
vaules for the variable can exceed 320000. Therefore the largest trace
buffer you can have is {\var 320000:320000} which means there will be
a maximum of 320000 entries of 320000 length buffers in the trace file.

\begin{verbatim}
pktTrace=<integer>[:<integer>]
\end{verbatim}

Specifies a medium level of trace detail, mainly information is saved
for each packet routed (e.g., packet length, IP addresses, TCP ports).
See {\var shorttrace} for information on the meaning of the integer
arguments.  Also see {\var pktTracePortIn} and {\var pktTracePortOut}.

\begin{verbatim}
trace=<integer>[:<integer>]
\end{verbatim}

Specifes the highest level of trace detail.  This option traces
everything a router does, and is used mostly for debugging.  Since
{\var trace} implies all of the tracing of {\var pktTrace}, the
options used to identify interfaces to be traced with {\var pktTrace}
(e.g., {\var pktTracePortIn}) can also be specified with {\var trace}.
See {\var shorttrace} for information on the integer arguments.

\begin{verbatim}
pktTracePortIn=<IP address>
\end{verbatim}

If {\var pktTrace} is specified, save trace information for packets
arriving on the router interface specified by {\var <IP address>}.  If
you wish to trace multiple ports, include multiple {\var
pktTracePortIn} options, one for each port.

\begin{verbatim}
pktTracePortOut=<IP address>
\end{verbatim}

If {\var pktTrace} is specified, save trace information for packets
leaving by the router interface specified by {\var <IP address>}.  If
you wish to trace multiple ports, include multiple {\var
pktTracePortOut} options, one for each port.

\begin{verbatim}
traceIn=<IP address>
\end{verbatim}

In conjunction with any trace function (e.g., {\var shorttrace}, {\var
pktTrace}, or {\var trace}), traces the average number of bytes/second
arriving on the specified interface.  If you wish to trace multiple
ports, include multiple {\var traceIn} options, one for each port.

\begin{verbatim}
traceOut=<IP address>
\end{verbatim}

In conjunction with any trace function (i.e., {\var shorttrace}, {\var
pktTrace}, or {\var trace}), traces the average number of bytes/second
sent on the specified interface.  If you wish to trace multiple ports,
include multiple {\var traceOut} options, one for each port.

\begin{verbatim}
traceInOut=<IP address>
\end{verbatim}

In conjunction with any trace function (i.e., {\var shorttrace}, {\var
pktTrace}, or {\var trace}), traces the average number of bytes/second
arriving on any interface, but directed to the specified interface.
Note that this number may be higher than the {\var traceOut} for the
same interface, since more packets may be arriving than the bandwidth
of the outgoing link can accommodate.  If you wish to trace multiple
ports, include multiple {\var traceInOut} options, one for each port.

\begin{verbatim}
pktTraceBeginTime=<real>[unit]
pktTraceEndTime=<real>[unit]
\end{verbatim}

Denote an interval during which to save packet traces.  Frequently,
packet traces are not of interest until traffic connections have
stabilized, so the interval can exclude the first few seconds of a
simulation.  The optional {\var unit} can be {\var s} (seconds), {\var
ms} (milliseconds), or {\var us} (microseconds). The default is
milliseconds.

\begin{verbatim}
timeInc=<integer>[unit]
\end{verbatim}

Specifies a time period used by some of the trace functions.
Functions {\var traceIn}, {\var traceInOut}, {\var traceOut}, and
{\var traceQueue} compute an average and a minimum/maximum over this
time period, at the end of which a trace entry is saved and a new
interval begun.  The default value is 100ms.  The optional unit can be
{\var us} (microseconds), {\var ms} (milliseconds), or {\var s}
(seconds). The default unit is microseconds.  Multiple {\var timeInc}
options can be specified per line, and the ordering of arguments is
important.  When a {\var timeInc} is encountered, all appropriate
trace functions following this {\var timeInc} will use its time
period, until another {\var timeInc} occurs.  This allows a different
tracing granularity to be used for separate network interfaces.

\begin{verbatim}
traceQueue=<IP address>
\end{verbatim}

In conjunction with any trace function (i.e., {\var shorttrace}, {\var
pktTrace}, or {\var trace}), traces the minimum, maximum, and average
number of packets queued to be sent on the specified interface.  If
you wish to trace multiple ports, include multiple {\var traceQueue}
options, one for each port.

\begin{verbatim}
traceQueueLen=<IP address>
\end{verbatim}

In conjunction with any trace function (i.e., {\var shortTrace}, {\var
pktTrace}, or {\var trace}), this option traces the minimum, maximum,
and average number of bytes queued to be sent on the specified
interface.  This option works like {\var traceQueue}, except that the
number of {\it bytes} in the queue are traced, rather than the number
of {\it packets}.

\subsubsection{Random Early Detection ({\var RED})}\label{RED}
A {\var RED} router queues and forwards packets in the order in which
they arrive, but also implements the RED algorithm to control the
queue sizes in the routers.  Each output port of the router has a
queue associated with it.  These queues are of limited size,
and packets routed to an output port while its queue is full or if the
RED algorithm decides packets are dropped by the router. For more
information on the RED algorithm see \cite{Van93TransNet}.

The following arguments can be used with the router. They have the
same meanings as specified above for the FCFS router.

\begin{verbatim}

buf=<integer>
shortTrace=<integer>[:<integer>]
pktTrace=<integer>[:<integer>]
trace=<integer>[:<integer>]
pktTracePortIn=<IP address>
pktTracePortOut=<IP address>
traceIn=<IP address>
traceOut=<IP address>
traceInOut=<IP address>
pktTraceBeginTime=<real>[unit]
pktTraceEndTime=<real>[unit]
timeInc=<integer>[unit]
traceQueue=<IP address>
traceQueueLen=<IP address>

\end{verbatim}
 Other options specific to the {\var RED} router which speicify {\var RED}
 parameters include

\begin{verbatim}
minThresh=<integer>
\end{verbatim}
This sets the size of the queue for the minimum threshold for the
{\var RED}
algorithm. IF no value is specified this defaults to zero.

\begin{verbatim}
maxThresh=<integer>
\end{verbatim}
This sets the size of the queue for the maximum threshold for the {\var
RED }
algorithm. If no value is specified this defaults to the number of
router buffers - 10.

\begin{verbatim}
qWeight=<real>
\end{verbatim}

This specifies the queue weight for the average queue calucation for
the {\var RED} algorithm. If now value is specified the default is {\var 0.008}


