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

\subsection {The {\var host} Entry}\label{hostApp}

The {\var host} entries are used to configure the protocol stacks of
the hosts attached to the internetwork.  The actions a host takes when
the simulator is run is determined by its protocol stack, especially
by the ``application-level'' protocol(s) (i.e., {\var megtest} and/or
{\var traffic}) located at the top of the stack.

The only difference between a simulated host's protocol graph in {\xs}
and a real host's protocol graph in the {\xk} is that they specified
through different means.  In the {\xk}, the {\var graph.comp} file
configures the protocol graph.  In {\xs}, the {\var graph.comp} file
is used only to determine which protocols to include in the simulator
executable; the relationships between the protocols are ignored.  The
simulator uses the {\var host} entries in the {\var xsim.data} file to
configure protocol graphs for each host.  Note that although we have
created special, heavily-instrumented, versions of many protocols,
{\it any} {\xk} protocol can be included in the simulator.

The syntax of a host entry is:

\begin{verbatim}
host <name>;
  protocols = <hlp> <llp> <llp> ... , <hlp> <llp> <llp> ... , ... ;
  args = <arg> <arg> ... ;
  pargs <protocol instance> = <arg> <arg> ... ;
  pargs <protocol instance> = <arg> <arg> ... ;
  ...
\end{verbatim}

\noindent
The name given in the {\var host} line must match the name given in
the {\var net} entry.

The {\var protocols} line configures the protocol stack running on the
simulated host.  It consists of groups of protocols separated by
commas.  The first protocol in a group ({\var hlp}) is configured over
the remaining protocols ({\var llp}) in the same group.

There are a couple of points to be aware of when building a host's
protocol graph.  First, all protocol graphs in the simulator must
contain the special {\var sim} protocol on the bottom.  Second, an
application-level protocol like {\var megtest} or {\var traffic} must
be placed at the top of the stack, otherwise the hosts will not have
any reason to send data to each other 

\begin{figure}[ht]
\centering
\leavevmode\hbox{\epsfig{file=graph.eps,height=3.0in}}
\caption{Example protocol graph}\label{graph2}
\end{figure}
 
The following sections contain more information about these, and
other, special simulator protocols. Figure~\ref{graph2} shows a
typical protocol graph.  This graph is represented in the {\var
protocol} line of a {\var host} entry as shown below.

\begin{verbatim}
 protocols = megtest rtcp, rtcp ip, ip vnet, vnet eth arp, arp eth, 
             eth ethd, ethd sim;
\end{verbatim}
 
Many protocols accept configuration parameters; the {\var args} line
lists those parameters that all the protocols interpret.  Each
protocol instance, at initialization, scans through the {\var args}
line to see if it contains any arguments that the protocol
understands.

In addition to, or in place of, the {\var args} line, there can occur
one or more {\var pargs} lines ({\var pargs} stands for ``protocol
args'').  A {\var pargs} line allows you to an specify argument list
for a specific protocol instance that appeared in the {\var protocols}
line.

An argument listed on the {\var args} line is interpreted by {\it all}
protocol instances that understand the argument.  However, a {\var
pargs} entry becomes necessary when multiple instances of a protocol
are configured on a host, and each instance must be given different
parameters.  For example, assume that a host's protocol stack contains
two instances of the Ethernet driver, named {\var ethd/1} and {\var
ethd/2}.  An {\var -ethdDelay} argument meant exclusively for the
{\var ethd/2} instance may be specified as:

\begin{verbatim}
  pargs ethd/2 = -ethdDelay=10us;
\end{verbatim}

The following subsections list, by protocol, arguments that can be
included on the {\var args} and {\var pargs} lines.

\subsubsection {Simulator Interface ({\var sim})}

{\var sim} is a protocol that lies at the bottom of the protocol
graph. It {\var sim}ulates the networks and routers that make up an
internetwork.  Passing a message to the {\var sim} protocol is
equivalent to putting it onto a network's physical wire. The {\var
sim} protocol then {\var sim}ulates the message's journey through the
modeled network until it reaches a protocol subgraph representing the
final destination host, at which time {\var sim} passes the message up
to that host's protocol graph. {\var sim} also replies to ARP and RARP
requests made by hosts.  Special protocols, called driver protocols,
are used between standard {\xk} protocols and the {\var sim} protocol.
There are no arguments used with the {\var sim} protocol.

\subsubsection {Ethernet Driver ({\var ethd})}\label{ethdsim}

The {\var ethd} protocol is the ``device driver'' that a host uses to
connect to either an Ethernet or a point-to-point link.  The following
arguments for {\var ethd} may be specified on an {\var args} or {\var
pargs} line.

\begin{verbatim}
-ethdDelay=<integer>
\end{verbatim}
 
Used to simulate the time it takes, in microseconds, for a host to
process a packet.  During the time period specified, the host cannot
accept or process any other packets.  If this option is not specified,
hosts are assumed to be infinitely fast.
 
\begin{verbatim}
-ethdDelayRange=<integer>
\end{verbatim}
 
A random number of microseconds is added to each delay period
specified by {\var -ethdDelay}.  If the argument given is $x$, then
the interval of the modification is between $-x$ and $x$.  Note that
the range specified should be less than or equal to the delay
specified using {\var -ethdDelay}.
 
\begin{verbatim}
-ethdQueue=<integer>
\end{verbatim}

Specifies the maximum number of messages that can be queued for
transmission by ETHD. This is useful when using hosts running IP as
routers; it is the only way to specify the maximum queue size for the
router outports.

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

Indicates that the Ethernet driver protocol should save trace
information (e.g., opens, sends, drops) and specifies the amounts of
memory and disk space that may be used for this purpose.  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 no colon and second argument is specified, this number
also represents the maximum size of the trace file.  The second
argument specifies the maximum number of memory buffers that the disk
file may contain.  See the explanation of {\var shortTrace} in
Section~\ref{FCFS} for an example.

\begin{verbatim}
-ethdTraceIn
\end{verbatim}
 
In conjunction with {\var -ethdTrace}, traces the average number of
bytes/second arriving on the interface associated with the {\var ethd}
driver.

\begin{verbatim}
-ethdTraceOut
\end{verbatim}
 
In conjunction with {\var -ethdTrace}, traces the average number of
bytes/second sent on the interface associated with {\var ethd}
 
\subsubsection {Big Window TCP ({\var btcp})}\label{btcpsim}

An adaptation of BSD Lite's Big Window TCP.  Big Window TCP is an
implementation of a TCP extension that allows send windows greater
than 64KB in size.  See RFC 1323 for more information on Big Window
TCP. The following arguments for {\var btcp} may be specified on an
{\var args} or {\var pargs} line.

\begin{verbatim}
-tcpAcknow
\end{verbatim}
 
If this option is specified, the protocol acknowledges every segment.
The default is to send an ACK for every 2nd segment, or upon
expiration of the fast timeout.
 
\begin{verbatim}
-tcpSlowstart=<integer>
\end{verbatim}
 
Specifies the size of the window, in segments, at the beginning of
slow start.  The default is 1.  This option is included for
experimental purposes.
 
\begin{verbatim}
-tcpTimer=<integer>
\end{verbatim}
 
Specifies a delay, in microseconds, before starting the TCP fast and
slow timeouts.  Without some timer delay, all hosts in a simulation
will experience timeouts simultaneously -- this could lead to strange
simulation results.  The preferred alternative to manually specifying
a different delay for each host is to use {\var -tcpTimerAuto}.
 
\begin{verbatim}
-tcpTimerAuto
\end{verbatim}
 
Instructs the simulator to stagger the start delay for the timers on
each host.  If the duration of a timer is $t$, and there are $n$
hosts, the hosts' timers are started at intervals of {\it t/n}
milliseconds.  For example, the fast timeout fires at intervals of 200
ms.  If there were four hosts, their fast timeouts would be started
after delays of 0, 50, 100, and 150 ms.  Thus, every timer is given a
unique start delay.
 
\begin{verbatim}
-tcpTrace=<integer>[:<integer>]
\end{verbatim}
 
Trace events of importance to TCP, such as the transmission of a
segment, the size of the send window, and the firing of a timeout.
The function of the arguments is the same as with the {\var
-ethdTrace} option. (See Section~\ref{ethdsim}.)
 
\subsubsection {TCP Reno ({\var rtcp})}\label{rtcpsim} 

Historically, TCP Reno superceded TCP Tahoe.  Reno differs from Tahoe
in that the it ACKs every other packet and uses the Fast Recovery
mechanism. The arguments used with {\var rtcp} are identical to those
used with {\var btcp} arguments.

\begin{verbatim}
-tcpAcknow  
-tcpSlowstart=<integer>
-tcpTimer=<integer>
-tcpTimerAuto
-tcpTrace=<integer>[:<integer>]
\end{verbatim}

\noindent
See Section~\ref{btcpsim} for information on these options.

\subsubsection {TCP Tahoe ({\var ttcp})}\label{ttcpsim}

The arguments used with {\var ttcp} are identical to those used with
{\var btcp}, with the exception that {\var -tcpAcknow} has no meaning.
This is because {\var ttcp} sends an ACK for every packet it receives.

\begin{verbatim}
-tcpSlowstart=<integer>
-tcpTimer=<integer>
-tcpTimerAuto
-tcpTrace=<integer>[:<integer>]
\end{verbatim}

\noindent
See Section~\ref{btcpsim} for information on these options.
 
\subsubsection {TCP Vegas ({\var vtcp})}\label{vtcpsim}

TCP Vegas is a version of TCP, developed at the University of Arizona,
that uses a congestion avoidance strategy to decrease losses and
improve throughput over TCP Reno.  Arguments common to the other TCPs
may be used on the {\var args} and {\var pargs} lines.

\begin{verbatim}
-tcpAcknow
-tcpSlowstart=<integer>
-tcpTimer=<integer>
-tcpTimerAuto
-tcpTrace=<integer>[:<integer>]
\end{verbatim}

\noindent
See Section~\ref{btcpsim} for information on these options. In
addition, several arguments are specific to TCP Vegas.

\begin{verbatim}
-tcpTop=<integer>
\end{verbatim}
 
The $\alpha$ parameter used by TCP Vegas to specify the minimum number
of extra router buffers to use when not in slow start.  The default is
1.

\begin{verbatim}
-tcpBot=<integer>
\end{verbatim}
 
The $\beta$ parameter used by TCP Vegas to specify the maximum number
of extra router buffers to use when not in slow start.  The default is
3.
 
\begin{verbatim}
-tcpExp=<integer>
\end{verbatim}
 
Specifies the maximum number of extra router buffers to use in slow
start.  The default is 1.
 
\begin{verbatim}
-tcpFlags=[e|E][s|S][c|C][p|P]
\end{verbatim}
 
This option is followed by a string of up to four letters, each of
which enables (lower case) or disables (upper case) the corresopnding
{\var vtcp} option.
 
\begin{itemize}

\item{} {\var [e|E]}: Enable/disable congestion avoidance during slow start.  

\item{} {\var [s|S]}: Enable/disable spike prevention (experimental).

\item{} {\var [c|C]}: Enable/disable congestion avoidance.

\item{} {\var [p|P]}: Enable/disable prediction during slow start.  
Predicts the connection bandwidth, so that slow start ends sooner.

\end{itemize}

\noindent
Both congestion avoidance options are enabled by default, and the
others are disabled.  Thus, specifying {\var p} as an argument is the
same as {\var eScp}.
 
\subsubsection {Megabyte Stream Test ({\var megtest})}\label{megtest}

{\var megtest} is an application-level protocol, that is, it sits at
the top of the protocol stack and determines the actions taken by a
host during a simulation.  A {\var megtest} client opens a TCP
connection to a {\var megtest} server and streams data (default is one
megabyte) to the server.  The {\var megtest} protocol allows us to
measure and compare the throughput of the various TCP protocols.
The following arguments for {\var megtest} may be specified on an
{\var args} or {\var pargs} line.

\begin{verbatim}
-buf=<integer>
\end{verbatim}
 
Specifies the size, in kilobytes, of the TCP send and receive buffers.
 
\begin{verbatim}
-db=<filename>
\end{verbatim}
 
Specifies the filename in which to print general information about the
run.  If this option is not specified, this information is not saved.
 
\begin{verbatim}
-dbId=<integer>
\end{verbatim}
 
After the test, prints the line {\var id: <integer>} in the file
specified by the {\var -db} option.

\begin{verbatim}
-dbStr=<string>
\end{verbatim}
 
Specifies a string to print in the file specified by the {\var -db}
option after the run has ended.  This option is used to print
descriptive information about the run, so that multiple runs can be
output to the same file and later identified.  For example, if one of
the important characteristics of a simulation is that all routers use
30 buffers, then the argument, {\var -dbStr=rbufs:30} would print the
line {\var rbufs:30} in the output file immediately following the
trace information printed by the run. You can have up to 10 different
{\var -dbStr} per host.
 
\begin{verbatim}
-delay=<integer>[unit]
\end{verbatim}
 
The delay in (simulated) time units before the test starts.  The
optional {\var unit} can be one of {\var us} (microseconds), {\var ms}
(milliseconds), or {\var s} (seconds). The default unit is
milliseconds.  When running {\var megtest} in the presence of
background traffic, a delay of a few seconds should be specified in
order to give the background connections a chance to stabilize.
 
\begin{verbatim}
-killTraffic
\end{verbatim}
 
If given as an argument to a single host, after the {\var megtest} on
{\it this} host is done, the traffic is killed and the simulation
stops.  This option is usually used on the command line after {\var
-all}, where it signifies that after {\it all} {\var megtest}
protocols have completed their streaming, all traffic processes are
killed and the simulation stops.
 
\begin{verbatim}
-len=<integer>
\end{verbatim}
 
Sets the amount of data, in kilobytes, to be transferred by the test.
The default is 1024, that is, 1MB.
 
\begin{verbatim}
-megTime=<integer>[unit]
\end{verbatim}
 
Stop the {\var megtest} after it has been allowed to run for the
specified number of time units, even if the transfer has not
completed.  The optional {\var unit} can be {\var us} (microseconds),
{\var ms} (milliseconds), or {\var s} (seconds). The default unit is
seconds.
 
\begin{verbatim}
-reset=<integer>
\end{verbatim}
 
Resets TCP trace information after the specified number of seconds.
Often, data about transfers is only of interest after the traffic has
had a chance to stabilize, which usually takes a few (simulated)
seconds.
 
\begin{verbatim}
-serverPort=<integer>
\end{verbatim}
 
Used if a single host is running multiple {\var megtest} servers,
where each server instance must be assigned a port to listen on.  A
{\var megtest} client specifies which server on the host it wants to
talk to, by specifying the appropriate port in the client's {\var
-serverPort} option.

\begin{verbatim}
-showTime
\end{verbatim}
 
If this option is given, every so often the {\var megtest} process
prints the elapsed time.
 
\begin{verbatim}
-thresh=<integer>
\end{verbatim}
 
Specifies the initial threshold variable for TCP's slow start, in 1KB
units.  The default is one half of the buffer size specified by the
{\var -buf} option.
 
\subsubsection {Background Internet Traffic ({\var traffic})}\label{traffic} 

Like {\var megtest}, {\var traffic} is an application-level protocol.
The {\var traffic} protocol simulates typical Internet traffic based
on {\it tcplib}---a library that models Internet traffic sources that
is based on empirical data collected at different Internet gateways.

{\var traffic} starts conversations with interarrival times given by an
exponential distribution. Each conversation can be of type TELNET,
FTP, NNTP or SMTP, and each expects a set of parameters. For example,
FTP conversations are parameterized by the number of items to
transmit, control segment sizes, and the individual item sizes. All of
these parameters are obtained from {\it tcplib} and are based on
probability distributions obtained from real traffic traces. Finally,
each of these conversations runs on top of its own TCP connection.

The startup distribution of {\var traffic} conversations is determined
solely by the initial seeds given to the {\var traffic} protocol, and
not by the lower protocols.  Therefore, two {\var traffic} simulations
started with the same seeds will start the same {\it tcplib}
conversations at the same times.  This is important for reproducing
experiments, or for guaranteeing that observed behavior difference
between protocols is not due to different traffic patterns.
 
By default, {\var traffic} hosts are servers and not clients.  In
other words, unless otherwise specified, a {\var traffic} host will
respond to requests to open connections but will not initiate
connections.  Use the {\var -hosts} or {\var -rhosts} options to
create {\var traffic} clients.  A {\var traffic} host can be both a
client and a server.
 
The following arguments for the {\var traffic} protocol may be
specified on an {\var args} or {\var pargs} line.

\begin{verbatim}
-cit=<interval>
\end{verbatim}
 
Specifies the average connection interarrival time (CIT) to be used at
equilibrium.  This time is used by the {\var traffic} protocol to
decide when to open new connections; the {\var traffic} protocol
should space new connections by this interval, on average.  Note that
a lower CIT means that connections are opened more frequently, leading
to a greater overall number of open connections.  See the {\var
-begcit}, {\var -begdur}, and {\var -begint} options for opening
connections at simulator startup.  See Figure~\ref{cit} for a diagram
that illustrates the relationship among these parameters.

\begin{figure}[ht]
\centering
\leavevmode\hbox{\epsfig{file=cit.eps,height=2.0in}}
\caption{Interaction of CIT Parameters}\label{cit}
\end{figure}
 
\begin{verbatim}
-begcit=<integer>
\end{verbatim}
 
Since there are no open connections at the beginning of a simulation,
it is often desirable to open a lot of connections at once; setting
this variable to a number lower than that used with the {\var -cit}
option will allow connections to be opened more quickly.  This number
is used as the connection interarrival time until the interval
specified with {\var -begint} has elapsed.
 
\begin{verbatim}
-begdur=<integer>
\end{verbatim}
 
Specifies the number of seconds to elapse after starting a simulation
before the number specified by {\var -cit} is used as the connection
interarrival time.  Between the end of the time specified by {\var
-begint} and {\var -begdur}, the CIT grows linearly toward the level
specified by the {\var -cit} option.
 
\begin{verbatim}
-begint=<integer>
\end{verbatim}
 
Specifies the number of seconds that the CIT specified by {\var
-begcit} should be used, before the CIT is allowed to grow linearly
towards that specified with the {\var -cit} option.
 
\begin{verbatim}
-begkeep=<integer>
\end{verbatim}
 
Rather than creating a new thread for each new {\var traffic}
connection and destroying them after the connection closes, the {\var
traffic} protocol caches the threads for later use.  The number of
threads in the cache will be equal to the maximum number of
connections that have been open simultaneously.  Since a large number
of connections may be opened at the beginning of the simulation by the
parameters described above, the cache may contain more threads than
will be needed by the rest of the simulation.  This option allows
excess threads to be freed from the cache.  It specifies that the
simulator should only keep the specified number of threads in cache;
if later it needs more, it will reallocate them.  This is an
optimization feature---it may improve the running time of a
simulation, but will not affect its results in any way.  The default
value is 100.
 
\begin{verbatim}
-db=
-dbStr=
\end{verbatim}
 
These options are the same as specified in Section~\ref{megtest}.
 
%\begin{verbatim}
%-fhd=<integer 1> <integer 2> ...
%\end{verbatim}
 
%This option specifies the percentage of FTP connections that {\var
%traffic} should establish to different hosts.  The argument list is
%composed of $n$ integers, where $n$ is the number of hosts specified
%after the {\var -hosts} or {\var -rhosts} options; the sum of all
%arguments should be 100.  Each argument indicates the percentage of
%FTP connections that should go to the server listed in the same
%position under {\var -hosts}.  The first integer is the percentage of
%FTP connections that will go to the first server specified, the second
%integer corresponds to the second server, and so on.  If the {\var
%-rhosts} option is specified instead, then the integers correspond to
%the hosts randomly selected by the simulator.
 
\begin{verbatim}
-ftpBufSize=<integer>
\end{verbatim}
 
Sets the send buffer size, in kilobytes, for FTP connections generated
by the {\var traffic} protocol.  The default is 20, that is, 20KB.
 
\begin{verbatim}
-hold=[f][n][s][t]
\end{verbatim}
 
Tells the {\var traffic} host never to start a particular kind of
connection.  The arguments correspond to the first letters of the
types of {\it tcplib} connections: {\var f} is FTP, {\var n} is NNTP,
{\var s} is SMTP, and {\var t} is TELNET.  Thus {\var -hold=ft}
specifies that the {\var traffic} host should never begin an FTP or a
TELNET connection.
 
\begin{verbatim}
-hosts=<integer> <IP addr 1> <IP addr 2> ...
\end{verbatim}
 
Specifies that this host will be a {\var traffic} client, and lists
the servers with which the client will randomly establish connections.
The first argument is the number of servers, and the remaining
arguments specify the IP addresses of the {\var traffic} servers.
 
%\begin{verbatim}
%-nhd=<integer 1> <integer 2> ...
%\end{verbatim}
 
%Specifies the percentage of NNTP connections generated by the {\var
%traffic} protocol that will go to each server.  See the {\var -fhd}
%option for information on the meaning of the arguments.
 
\begin{verbatim}
-otherBufSize=<integer>
\end{verbatim}
 
Sets the send buffer size, in kilobytes, for non-FTP transfers.  The
default is 10, that is 10KB.
 
\begin{verbatim}
-reset=<integer>
\end{verbatim}
 
Resets the information accumulated about {\var traffic} transfers
after the specified number of seconds.  Often, data about transfers is
only of interest after the traffic has had a chance to stabilize,
which usually takes a few (simulated) seconds.
 
\begin{verbatim}
-rhosts=<integer>
\end{verbatim}
 
Provides an alternative to the {\var -hosts} option when the user does
not want to specify the IP addresses of the {\var traffic} servers.
Like {\var -hosts}, this option specifies that the host is a client.
At startup, the simulator randomly picks the specified number of hosts
out of the pool of {\var traffic} hosts, and the client will establish
connections to only this subset of hosts.  Note that the selection
occurs from all {\var traffic} hosts, even if they are not servers.
Therefore, it is recommended that all hosts are designated as servers
if this option is used.
 
\begin{verbatim}
-s
\end{verbatim}
 
Specifies that the host is a server.  This is the default.  A host can
be both a client and a server.
 
\begin{verbatim}
-s0
\end{verbatim}

Specifies that the host is not a server. 
 
\begin{verbatim}
-seed=<integer>
\end{verbatim}
 
Specifies a seed to be used by that host to begin the random number
function that determines the distribution of {\var traffic}
connections.  Usually, this option is not used. Instead, a global seed
is specified on the command line, and this seed is automatically
modified by the host name to produce one that is unique for each
simulated host.  See the {\var -seed} command-line option.
 
%\begin{verbatim}
%-shd=<integer 1> <integer 2> ...
%\end{verbatim}
 
%Specifies the percentage of SMTP connections generated by the {\var
%traffic} protocol that will go to each server.  See the {\var -fhd}
%option for information on the meaning of the arguments.
 
\begin{verbatim}
-showTraffic
\end{verbatim}
 
When the simulation ends, prints some summary information about the
traffic for that simulation; this is the default if there are less
than 10 traffic hosts. Otherwise, this option must be specified for
each host from which the summary is desired.
 
%\begin{verbatim}
%-thd=<integer 1> <integer 2> ...
%\end{verbatim}
 
%Specifies the percentage of TELNET connections generated by the {\var
%traffic} protocol that will go to each server.  See the {\var -fhd}
%option for information on the meaning of the arguments.
 
\begin{verbatim}
-trafficTime=<integer>[unit]
\end{verbatim}
 
Stops the {\var traffic} test after it has been allowed to run for the
specified number of time units.  The optional {\var unit} can be {\var
us} (microseconds), {\var ms} (milliseconds), or {\var s} (seconds).
The default unit is seconds.
 
\begin{verbatim}
-trafficTrace=<integer>[:<integer]
\end{verbatim}
 
Saves trace information generated by the {\var traffic} protocols.
The meanings of the integer arguments are the same as those of the
{\var -ethdTrace} option. (See Section~\ref{ethdsim}.)

