% % 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 ; protocols = ... , ... , ... ; args = ... ; pargs = ... ; pargs = ... ; ... \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= \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= \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= \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=[:] \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= \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= \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=[:] \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= -tcpTimer= -tcpTimerAuto -tcpTrace=[:] \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= -tcpTimer= -tcpTimerAuto -tcpTrace=[:] \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= -tcpTimer= -tcpTimerAuto -tcpTrace=[:] \end{verbatim} \noindent See Section~\ref{btcpsim} for information on these options. In addition, several arguments are specific to TCP Vegas. \begin{verbatim} -tcpTop= \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= \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= \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= \end{verbatim} Specifies the size, in kilobytes, of the TCP send and receive buffers. \begin{verbatim} -db= \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= \end{verbatim} After the test, prints the line {\var id: } in the file specified by the {\var -db} option. \begin{verbatim} -dbStr= \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=[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= \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=[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= \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= \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= \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= \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= \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= \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= \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= \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= ... %\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= \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= ... \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= ... %\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= \end{verbatim} Sets the send buffer size, in kilobytes, for non-FTP transfers. The default is 10, that is 10KB. \begin{verbatim} -reset= \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= \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= \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= ... %\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= ... %\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=[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=[: