1.1 --- a/doc/manual/manual.texi Thu Sep 18 15:29:00 2008 -0700
1.2 +++ b/doc/manual/manual.texi Sat Sep 20 15:45:31 2008 -0700
1.3 @@ -84,6 +84,7 @@
1.4 * Packets::
1.5 * Sockets APIs::
1.6 * Node and Internet Stack::
1.7 +* TCP::
1.8 * Routing overview::
1.9 * Troubleshooting
1.10 @end menu
1.11 @@ -95,6 +96,7 @@
1.12 @include sockets.texi
1.13 @include node.texi
1.14 @c @include output.texi
1.15 +@include tcp.texi
1.16 @include routing.texi
1.17 @c @include other.texi
1.18 @include troubleshoot.texi
2.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
2.2 +++ b/doc/manual/tcp.texi Sat Sep 20 15:45:31 2008 -0700
2.3 @@ -0,0 +1,342 @@
2.4 +@node TCP
2.5 +@chapter TCP models in ns-3
2.6 +@anchor{chap:TCP}
2.7 +
2.8 +This chapter describes the TCP models available in ns-3.
2.9 +
2.10 +@section Generic support for TCP
2.11 +
2.12 +ns-3 was written to support multiple TCP implementations. The
2.13 +implementations inherit from a few common header classes in the
2.14 +@code{src/node} directory, so that user code can swap out implementations
2.15 +with minimal changes to the scripts.
2.16 +
2.17 +There are two important abstract base classes:
2.18 +@itemize @bullet
2.19 +@item @code{class TcpSocket}: This is defined in @code{src/node/tcp-socket.{cc,h}}. This class exists for hosting TcpSocket attributes that can be
2.20 +reused across different implementations. For instance,
2.21 +@code{TcpSocket::SetInitialCwnd()} can be used for any of the implementations
2.22 +that derive from @code{class TcpSocket}.
2.23 +@item @code{class TcpSocketFactory}: This is used by applications to
2.24 +create TCP sockets. A typical usage can be seen in this snippet:
2.25 +@verbatim
2.26 + // Create the socket if not already created
2.27 + if (!m_socket)
2.28 + {
2.29 + m_socket = Socket::CreateSocket (GetNode(), m_tid);
2.30 + m_socket->Bind (m_local);
2.31 + ...
2.32 + }
2.33 +@end verbatim
2.34 +The parameter @code{m_tid} controls the TypeId of the actual Tcp Socket
2.35 +implementation that is instantiated. This way, the application can be
2.36 +written generically and different socket implementations can be swapped out
2.37 +by specifying the TypeId.
2.38 +@end itemize
2.39 +
2.40 +@section ns-3 TCP
2.41 +
2.42 +ns-3 contains a port of the TCP model from
2.43 +@uref{http://www.ece.gatech.edu/research/labs/MANIACS/GTNetS/index.html,,GTNetS}. This model is a full TCP, in that it is
2.44 +bidirectional and attempts to model the connection setup and
2.45 +close logic. In fact, it is a more complete implementation of the TCP
2.46 +state machine than ns-2's "FullTcp" model. This TCP model was originally
2.47 +written by George Riley
2.48 +as part of GTNetS and ported to ns-3 by Raj Bhattacharjea.
2.49 +
2.50 +The implementation of TCP is contained in the following files:
2.51 +@verbatim
2.52 +src/internet-stack/tcp-header.{cc,h}
2.53 +src/internet-stack/tcp-l4-protocol.{cc,h}
2.54 +src/internet-stack/tcp-socket-factory-impl.{cc,h}
2.55 +src/internet-stack/tcp-socket-impl.{cc,h}
2.56 +src/internet-stack/tcp-typedefs.h
2.57 +src/internet-stack/rtt-estimator.{cc,h}
2.58 +src/internet-stack/sequence-number.{cc,h}
2.59 +@end verbatim
2.60 +
2.61 +@subsection Usage
2.62 +
2.63 +The file @code{examples/tcp-star-server.cc} contains an example that
2.64 +makes use of @code{ns3::OnOffApplication} and @code{ns3::PacketSink}
2.65 +applications.
2.66 +
2.67 +Using the helper functions defined in @code{src/helper}, here is how
2.68 +one would create a TCP receiver:
2.69 +@verbatim
2.70 + // Create a packet sink on the star "hub" to receive these packets
2.71 + uint16_t port = 50000;
2.72 + Address sinkLocalAddress(InetSocketAddress (Ipv4Address::GetAny (), port));
2.73 + PacketSinkHelper sinkHelper ("ns3::TcpSocketFactory", sinkLocalAddress);
2.74 + ApplicationContainer sinkApp = sinkHelper.Install (serverNode);
2.75 + sinkApp.Start (Seconds (1.0));
2.76 + sinkApp.Stop (Seconds (10.0));
2.77 +@end verbatim
2.78 +
2.79 +Similarly, the below snippet configures OnOffApplication traffic
2.80 +source to use
2.81 +TCP:
2.82 +@verbatim
2.83 + // Create the OnOff applications to send TCP to the server
2.84 + OnOffHelper clientHelper ("ns3::TcpSocketFactory", Address ());
2.85 +@end verbatim
2.86 +
2.87 +The careful reader will note above that we have specified the TypeId
2.88 +of an abstract base class @code{TcpSocketFactory}. How does the
2.89 +script tell ns-3 that it wants the native ns-3 TCP vs. some other one?
2.90 +Well, when internet stacks are added to the node, the default
2.91 +TCP implementation that is aggregated to the node is the ns-3 TCP.
2.92 +This can be overridden as we show below when using Network
2.93 +Simulation Cradle. So, by default, when using the ns-3 helper API,
2.94 +the TCP that is aggregated to nodes with an Internet stack is the
2.95 +native ns-3 TCP.
2.96 +
2.97 +Once a TCP socket is created, you will want to follow conventional
2.98 +socket logic and either connect() and send() (for a TCP client)
2.99 +or bind(), listen(), and accept() (for a TCP server).
2.100 +@xref{Sockets APIs,,Sockets API} for a review of how sockets are used
2.101 +in ns-3.
2.102 +
2.103 +To configure behavior of TCP, a number of parameters are exported through
2.104 +the @ref{Attributes,,ns-3 attribute system}. These are documented in the
2.105 +@uref{http://www.nsnam.org/doxygen/classns3_1_1_tcp_socket.html,,Doxygen}
2.106 +for @code{class TcpSocket}.
2.107 +
2.108 +@subsection Current limitations
2.109 +@itemize @bullet
2.110 +@item Only Tahoe congestion control is presently supported.
2.111 +@item Only IPv4 is supported (IPv6 support will start to be added in ns-3.3).
2.112 +@item @uref{http://www.nsnam.org/bugzilla/show_bug.cgi?id=198,,Bug 198}: TcpSocketImpl doesn't send acks with data packets in two-way transfers
2.113 +@item @uref{http://www.nsnam.org/bugzilla/show_bug.cgi?id=250,,Bug 250}: Tcp breaks if you set the DelAckCount parameter to be greater than 2
2.114 +@item @uref{http://www.nsnam.org/bugzilla/show_bug.cgi?id=311,,Bug 311}: Tcp socket close returns -1 but does not set errno.
2.115 +@end itemize
2.116 +
2.117 +@section Network Simulation Cradle
2.118 +
2.119 +The @uref{http://www.wand.net.nz/~stj2/nsc/,,Network Simulation Cradle (NSC)}
2.120 +is a framework for wrapping real-world network
2.121 +code into simulators, allowing simulation of real-world behavior at little
2.122 +extra cost. This work has been validated by comparing situations using
2.123 +a test network with the same situations in the simulator. To date, it has
2.124 +been shown that the NSC is able to produce extremely accurate results.
2.125 +NSC supports four real world stacks: FreeBSD, OpenBSD, lwIP and Linux.
2.126 +Emphasis has been placed on not changing any of the network stacks by hand.
2.127 +Not a single line of code has been changed in the network protocol
2.128 +implementations of any of the above four stacks. However, a custom C
2.129 +parser was built to programmatically change source code.
2.130 +
2.131 +NSC has previously been ported to ns-2 and OMNeT++, and recently
2.132 +was added to ns-3. This section describes the ns-3 port of NSC and
2.133 +how to use it.
2.134 +
2.135 +@subsection Prerequisites
2.136 +
2.137 +Presently, NSC has been tested and shown to work on these platforms:
2.138 +Linux i386 and Linux x86-64. NSC does not support powerpc at the moment.
2.139 +
2.140 +NSC requires the packages mercurial, flex, and bison.
2.141 +
2.142 +@subsection Configuring and Downloading
2.143 +
2.144 +NSC is disbled by default and must be explicitly configured in. To try
2.145 +this, type
2.146 +@verbatim
2.147 +./waf configure --enable-nsc
2.148 +@end verbatim
2.149 +the output of the configuration will show something like:
2.150 +@verbatim
2.151 +Checking for NSC supported architecture x86_64 : ok
2.152 +Pulling nsc updates from https://secure.wand.net.nz/mercurial/nsc
2.153 +pulling from https://secure.wand.net.nz/mercurial/nsc
2.154 +searching for changes
2.155 +no changes found
2.156 +---- Summary of optional NS-3 features:
2.157 +...
2.158 +Network Simulation Cradle : enabled
2.159 +...
2.160 +@end verbatim
2.161 +if successful. Note that the configure script pulls a recent copy of
2.162 +NSC from a mercurial repository. This download will not work if you are not
2.163 +online.
2.164 +
2.165 +If everything went OK, you will see a directory called "nsc" in the top-level
2.166 +directory, with contents like this:
2.167 +@verbatim
2.168 +audit.sh linux-2.6/ openbsd3/ scons-time.py*
2.169 +ChangeLog linux-2.6.18/ README SConstruct
2.170 +config.log linux-2.6.26/ sconsign.py* sim/
2.171 +freebsd5/ lwip-1.3.0/ scons-LICENSE test/
2.172 +globaliser/ lwip-HEAD/ scons-local-1.0.1/
2.173 +INSTALL ns/ scons.py*
2.174 +LICENSE omnetpp/ scons-README
2.175 +@end verbatim
2.176 +
2.177 +@subsection Building and validating
2.178 +
2.179 +Building ns-3 with nsc support is the same as building it without; no
2.180 +additional arguments are needed for waf. Building nsc may take some time
2.181 +compared to ns-3; it is interleaved in the ns-3 building process.
2.182 +
2.183 +Try running the regression tests: @code{./waf --regression}. If NSC has
2.184 +been successfully built, the following test should show up in the results:
2.185 +@verbatim
2.186 +PASS test-tcp-nsc-lfn
2.187 +@end verbatim
2.188 +
2.189 +This confirms that NSC is ready to use.
2.190 +
2.191 +@subsection Usage
2.192 +There are a few example files. Try
2.193 +@verbatim
2.194 +./waf --run tcp-nsc-zoo
2.195 +./waf --run tcp-nsc-lfn
2.196 +@end verbatim
2.197 +These examples will deposit some @code{.pcap} files in your directory,
2.198 +which can be examined by tcpdump or wireshark.
2.199 +
2.200 +Let's look at the @code{examples/tcp-nsc-zoo.cc} file for some typical
2.201 +usage. How does it differ from using native ns-3 TCP? There is one
2.202 +main configuration line, when using NSC and the ns-3 helper API, that needs
2.203 +to be set:
2.204 +@verbatim
2.205 + InternetStackHelper internetStack;
2.206 +
2.207 + internetStack.SetNscStack ("liblinux2.6.26.so");
2.208 + // this switches nodes 0 and 1 to NSCs Linux 2.6.26 stack.
2.209 + internetStack.Install (n.Get(0));
2.210 + internetStack.Install (n.Get(1));
2.211 +@end verbatim
2.212 +
2.213 +The key line is the @code{SetNscStack}. This tells the InternetStack
2.214 +helper to aggregate instances of NSC TCP instead of native ns-3 TCP
2.215 +to the remaining nodes. It is important that this function be called
2.216 +@strong{before} callling the @code{Install()} function, as shown above.
2.217 +
2.218 +Which stacks are available to use? Presently, the focus has been on
2.219 +Linux 2.6.18 and Linux 2.6.26 stacks for ns-3. To see which stacks
2.220 +were built, one can execute the following find command at the ns-3 top level
2.221 +directory:
2.222 +@verbatim
2.223 +~/ns-3.2> find nsc -name "*.so" -type f
2.224 +nsc/linux-2.6.18/liblinux2.6.18.so
2.225 +nsc/linux-2.6.26/liblinux2.6.26.so
2.226 +@end verbatim
2.227 +This tells us that we may either pass the library name liblinux2.6.18.so or
2.228 +liblinux2.6.26.so to the above configuration step.
2.229 +
2.230 +@subsection Stack configuration
2.231 +NSC TCP shares the same configuration attributes that are common
2.232 +across TCP sockets, as described above and documented in
2.233 +@uref{http://www.nsnam.org/doxygen/classns3_1_1_tcp_socket.html,,Doxygen}
2.234 +
2.235 +Additionally, NSC TCP exports a lot of configuration variables into the
2.236 +ns-3 @ref{Attributes} system, via a @uref{http://en.wikipedia.org/wiki/Sysctl,,
2.237 +sysctl}-like interface. In the @code{examples/tcp-nsc-zoo} example, you
2.238 +can see the following configuration:
2.239 +@verbatim
2.240 + // this disables TCP SACK, wscale and timestamps on node 1 (the attributes represent sysctl-values).
2.241 + Config::Set ("/NodeList/1/$ns3::Ns3NscStack<linux2.6.26>/net.ipv4.tcp_sack", StringValue ("0"));
2.242 + Config::Set ("/NodeList/1/$ns3::Ns3NscStack<linux2.6.26>/net.ipv4.tcp_timestamps", StringValue ("0"));
2.243 + Config::Set ("/NodeList/1/$ns3::Ns3NscStack<linux2.6.26>/net.ipv4.tcp_window_scaling", StringValue ("0"));
2.244 +@end verbatim
2.245 +These additional configuration variables are not available to native ns-3
2.246 +TCP.
2.247 +
2.248 +@subsection NSC API
2.249 +
2.250 +This subsection describes the API that NSC presents to ns-3 or any other
2.251 +simulator. NSC provides its API in the form of a number of classes that
2.252 +are defined in @code{sim/sim_interface.h} in the nsc directory.
2.253 +
2.254 +@itemize @bullet
2.255 +@item @strong{INetStack}
2.256 +INetStack contains the 'low level' operations for the operating system
2.257 +network stack, e.g. in and output functions from and to the network stack
2.258 +(think of this as the 'network driver interface'. There are also functions
2.259 +to create new TCP or UDP sockets.
2.260 +@item @strong{ISendCallback}
2.261 +This is called by NSC when a packet should be sent out to the network.
2.262 +This simulator should use this callback to re-inject the packet into the
2.263 +simulator so the actual data can be delivered/routed to its destination,
2.264 +where it will eventually be handed into Receive() (and eventually back to the
2.265 +receivers NSC instance via INetStack->if_receive() ).
2.266 +@item @strong{INetStreamSocket}
2.267 +This is the structure defining a particular connection endpoint (file
2.268 +descriptor). It contains methods to operate on this endpoint, e.g. connect,
2.269 +disconnect, accept, listen, send_data/read_data, ...
2.270 +@item @strong{IInterruptCallback}
2.271 +This contains the wakeup callback, which is called by NSC whenever
2.272 +something of interest happens. Think of wakeup() as a replacement of the
2.273 +operating systems wakeup function: Whenever the operating system would
2.274 +wake up a process that has been waiting for an operation to complete (for
2.275 +example the TCP handshake during connect()), NSC invokes the wakeup() callback
2.276 +to allow the simulator to check for state changes in its connection endpoints.
2.277 +@end itemize
2.278 +
2.279 +@subsection ns-3 implementation
2.280 +
2.281 +The ns-3 implementation makes use of the above NSC API, and is implemented
2.282 +as follows.
2.283 +
2.284 +The three main parts are:
2.285 +@itemize @bullet
2.286 +@item @code{ns3::NscTcpL4Protocol}: a subclass of Ipv4L4Protocol (and two nsc classes: ISendCallback and IInterruptCallback)
2.287 +@item @code{ns3::NscTcpSocketImpl}: a subclass of TcpSocket
2.288 +@item @code{ns3::NscTcpSocketFactoryImpl}: a factory to create new NSC
2.289 +sockets
2.290 +@end itemize
2.291 +
2.292 +@code{src/internet-stack/nsc-tcp-l4-protocol} is the main class. Upon
2.293 +Initialization, it loads an nsc network stack to use (via dlopen()). Each
2.294 +instance of this class may use a different stack. The stack
2.295 +(=shared library) to use is set using the SetNscLibrary() method (at
2.296 +this time its called indirectly via the internet stack helper). The nsc
2.297 +stack is then set up accordingly (timers etc). The
2.298 +NscTcpL4Protocol::Receive() function hands the packet it receives (must be
2.299 +a complete tcp/ip packet) to the nsc stack for further processing.
2.300 +To be able to send packets, this class implements the nsc send_callback
2.301 +method. This method is called by nsc whenever the nsc stack wishes to
2.302 +send a packet out to the network. Its arguments are a raw buffer,
2.303 +containing a complete TCP/IP packet, and a length value. This method
2.304 +therefore has to convert the raw data to a Ptr<Packet> usable by ns-3.
2.305 +In order to avoid various ipv4 header issues, the nsc ip header is not
2.306 +included. Instead, the tcp header and the actual payload are put into the
2.307 +Ptr<Packet>, after this the Packet is passed down to layer 3 for sending
2.308 +the packet out (no further special treatment is needed in the send code
2.309 +path).
2.310 +
2.311 +This class calls @code{ns3::NscTcpSocketImpl} both from the nsc wakeup()
2.312 +callback and from the Receive path (to ensure that possibly queued data
2.313 +is scheduled for sending).
2.314 +
2.315 +
2.316 +@code{src/internet-stack/nsc-tcp-socket-impl} implements the nsc socket
2.317 +interface. Each instance has its own nscTcpSocket. Data that is Send()
2.318 +will be handed to the nsc stack via m_nscTcpSocket->send_data(). (and not
2.319 +to nsc-tcp-l4, this is the major difference compared to ns-3 TCP). The
2.320 +class also queues up data that is Send() before the underlying
2.321 +descriptor has entered an ESTABLISHED state. This class is called from
2.322 +the nsc-tcp-l4 class, when the nsc-tcp-l4 wakeup() callback is invoked by
2.323 +nsc. nsc-tcp-socket-impl then checks the current connection state
2.324 +(SYN_SENT, ESTABLISHED, LISTEN...) and schedules appropriate callbacks as
2.325 +needed, e.g. a LISTEN socket will schedule Accept to see if a new
2.326 +connection must be accepted, an ESTABLISHED socket schedules any pending
2.327 +data for writing, schedule a read callback, etc.
2.328 +
2.329 +Note that @code{ns3::NscTcpSocketImpl} does not interact with nsc-tcp
2.330 +directly: instead, data is redirected to nsc. nsc-tcp calls the
2.331 +nsc-tcp-sockets of a node when its wakeup callback is invoked by nsc.
2.332 +
2.333 +@subsection Limitations
2.334 +@itemize @bullet
2.335 +@item NSC only works on single-interface nodes; attempting to run it on
2.336 +a multi-interface node will cause a program error. This limitation should
2.337 +be fixed by ns-3.3.
2.338 +@item Cygwin and OS X PPC are not presently supported
2.339 +@item The non-Linux stacks of NSC are not supported
2.340 +@item NSC's integration into the build system presently requires on-line
2.341 +access and mercurial, and is a slow download.
2.342 +@end itemize
2.343 +
2.344 +For more information, see
2.345 +@uref{http://www.nsnam.org/wiki/index.php/Network_Simulation_Cradle_Integration,, this wiki page}.