.. include:: replace.txt

Building Topologies

-------------------

Building a Bus Network Topology

*******************************

In this section we are going to expand our mastery of |ns3| network 

devices and channels to cover an example of a bus network.  |ns3|

provides a net device and channel we call CSMA (Carrier Sense Multiple Access).

The |ns3| CSMA device models a simple network in the spirit of 

Ethernet.  A real Ethernet uses CSMA/CD (Carrier Sense Multiple Access with 

Collision Detection) scheme with exponentially increasing backoff to contend 

for the shared transmission medium.  The |ns3| CSMA device and 

channel models only a subset of this.

Just as we have seen point-to-point topology helper objects when constructing

point-to-point topologies, we will see equivalent CSMA topology helpers in

this section.  The appearance and operation of these helpers should look 

quite familiar to you.

We provide an example script in our examples/tutorial} directory.  This script

builds on the ``first.cc`` script and adds a CSMA network to the 

point-to-point simulation we've already considered.  Go ahead and open 

``examples/tutorial/second.cc`` in your favorite editor.  You will have already seen

enough |ns3| code to understand most of what is going on in this 

example, but we will go over the entire script and examine some of the output.

Just as in the ``first.cc`` example (and in all ns-3 examples) the file

begins with an emacs mode line and some GPL boilerplate.

The actual code begins by loading module include files just as was done in the

``first.cc`` example.

::

  #include "ns3/core-module.h"

  #include "ns3/simulator-module.h"

  #include "ns3/node-module.h"

  #include "ns3/helper-module.h"

One thing that can be surprisingly useful is a small bit of ASCII art that

shows a cartoon of the network topology constructed in the example.  You will

find a similar "drawing" in most of our examples.

In this case, you can see that we are going to extend our point-to-point

example (the link between the nodes n0 and n1 below) by hanging a bus network

off of the right side.  Notice that this is the default network topology 

since you can actually vary the number of nodes created on the LAN.  If you

set nCsma to one, there will be a total of two nodes on the LAN (CSMA 

channel) --- one required node and one "extra" node.  By default there are

three "extra" nodes as seen below:

::

// Default Network Topology

//

//       10.1.1.0

// n0 -------------- n1   n2   n3   n4

//    point-to-point  |    |    |    |

//                    ================

//                      LAN 10.1.2.0

Then the ns-3 namespace is ``used`` and a logging component is defined.

This is all just as it was in ``first.cc``, so there is nothing new yet.

::

  using namespace ns3;

  NS_LOG_COMPONENT_DEFINE ("SecondScriptExample");

The main program begins with a slightly different twist.  We use a verbose

flag to determine whether or not the ``UdpEchoClientApplication`` and

``UdpEchoServerApplication`` logging components are enabled.  This flag

defaults to true (the logging components are enabled) but allows us to turn

off logging during regression testing of this example.

You will see some familiar code that will allow you to change the number

of devices on the CSMA network via command line argument.  We did something

similar when we allowed the number of packets sent to be changed in the section

on command line arguments.  The last line makes sure you have at least one

"extra" node.

The code consists of variations of previously covered API so you should be

entirely comfortable with the following code at this point in the tutorial.

::

  bool verbose = true;

  uint32_t nCsma = 3;

  CommandLine cmd;

  cmd.AddValue ("nCsma", "Number of \"extra\" CSMA nodes/devices", nCsma);

  cmd.AddValue ("verbose", "Tell echo applications to log if true", verbose);

  cmd.Parse (argc,argv);

  if (verbose)

    {

      LogComponentEnable("UdpEchoClientApplication", LOG_LEVEL_INFO);

      LogComponentEnable("UdpEchoServerApplication", LOG_LEVEL_INFO);

    }

  nCsma = nCsma == 0 ? 1 : nCsma;

The next step is to create two nodes that we will connect via the 

point-to-point link.  The ``NodeContainer`` is used to do this just as was

done in ``first.cc``.

::

  NodeContainer p2pNodes;

  p2pNodes.Create (2);

Next, we declare another ``NodeContainer`` to hold the nodes that will be

part of the bus (CSMA) network.  First, we just instantiate the container

object itself.  

::

  NodeContainer csmaNodes;

  csmaNodes.Add (p2pNodes.Get (1));

  csmaNodes.Create (nCsma);

The next line of code ``Gets`` the first node (as in having an index of one)

from the point-to-point node container and adds it to the container of nodes

that will get CSMA devices.  The node in question is going to end up with a 

point-to-point device *and* a CSMA device.  We then create a number of 

"extra" nodes that compose the remainder of the CSMA network.  Since we 

already have one node in the CSMA network -- the one that will have both a

point-to-point and CSMA net device, the number of "extra" nodes means the

number nodes you desire in the CSMA section minus one.

The next bit of code should be quite familiar by now.  We instantiate a

``PointToPointHelper`` and set the associated default ``Attributes`` so

that we create a five megabit per second transmitter on devices created using

the helper and a two millisecond delay on channels created by the helper.

::

  PointToPointHelper pointToPoint;

  pointToPoint.SetDeviceAttribute ("DataRate", StringValue ("5Mbps"));

  pointToPoint.SetChannelAttribute ("Delay", StringValue ("2ms"));

  NetDeviceContainer p2pDevices;

  p2pDevices = pointToPoint.Install (p2pNodes);

We then instantiate a ``NetDeviceContainer`` to keep track of the 

point-to-point net devices and we ``Install`` devices on the 

point-to-point nodes.

We mentioned above that you were going to see a helper for CSMA devices and

channels, and the next lines introduce them.  The ``CsmaHelper`` works just

like a ``PointToPointHelper``, but it creates and connects CSMA devices and

channels.  In the case of a CSMA device and channel pair, notice that the data

rate is specified by a *channel* ``Attribute`` instead of a device 

``Attribute``.  This is because a real CSMA network does not allow one to mix,

for example, 10Base-T and 100Base-T devices on a given channel.  We first set 

the data rate to 100 megabits per second, and then set the speed-of-light delay

of the channel to 6560 nano-seconds (arbitrarily chosen as 1 nanosecond per foot

over a 100 meter segment).  Notice that you can set an ``Attribute`` using 

its native data type.

::

  CsmaHelper csma;

  csma.SetChannelAttribute ("DataRate", StringValue ("100Mbps"));

  csma.SetChannelAttribute ("Delay", TimeValue (NanoSeconds (6560)));

  NetDeviceContainer csmaDevices;

  csmaDevices = csma.Install (csmaNodes);

Just as we created a ``NetDeviceContainer`` to hold the devices created by

the ``PointToPointHelper`` we create a ``NetDeviceContainer`` to hold 

the devices created by our ``CsmaHelper``.  We call the ``Install`` 

method of the ``CsmaHelper`` to install the devices into the nodes of the

``csmaNodes NodeContainer``.

We now have our nodes, devices and channels created, but we have no protocol

stacks present.  Just as in the ``first.cc`` script, we will use the

``InternetStackHelper`` to install these stacks.

::

  InternetStackHelper stack;

  stack.Install (p2pNodes.Get (0));

  stack.Install (csmaNodes);

Recall that we took one of the nodes from the ``p2pNodes`` container and

added it to the ``csmaNodes`` container.  Thus we only need to install 

the stacks on the remaining ``p2pNodes`` node, and all of the nodes in the

``csmaNodes`` container to cover all of the nodes in the simulation.

Just as in the ``first.cc`` example script, we are going to use the 

``Ipv4AddressHelper`` to assign IP addresses to our device interfaces.

First we use the network 10.1.1.0 to create the two addresses needed for our

two point-to-point devices.

::

  Ipv4AddressHelper address;

  address.SetBase ("10.1.1.0", "255.255.255.0");

  Ipv4InterfaceContainer p2pInterfaces;

  p2pInterfaces = address.Assign (p2pDevices);

Recall that we save the created interfaces in a container to make it easy to

pull out addressing information later for use in setting up the applications.

We now need to assign IP addresses to our CSMA device interfaces.  The 

operation works just as it did for the point-to-point case, except we now

are performing the operation on a container that has a variable number of 

CSMA devices --- remember we made the number of CSMA devices changeable by 

command line argument.  The CSMA devices will be associated with IP addresses 

from network number 10.1.2.0 in this case, as seen below.

::

  address.SetBase ("10.1.2.0", "255.255.255.0");

  Ipv4InterfaceContainer csmaInterfaces;

  csmaInterfaces = address.Assign (csmaDevices);

Now we have a topology built, but we need applications.  This section is

going to be fundamentally similar to the applications section of 

``first.cc`` but we are going to instantiate the server on one of the 

nodes that has a CSMA device and the client on the node having only a 

point-to-point device.

First, we set up the echo server.  We create a ``UdpEchoServerHelper`` and

provide a required ``Attribute`` value to the constructor which is the server

port number.  Recall that this port can be changed later using the 

``SetAttribute`` method if desired, but we require it to be provided to

the constructor.

::

  UdpEchoServerHelper echoServer (9);

  ApplicationContainer serverApps = echoServer.Install (csmaNodes.Get (nCsma));

  serverApps.Start (Seconds (1.0));

  serverApps.Stop (Seconds (10.0));

Recall that the ``csmaNodes NodeContainer`` contains one of the 

nodes created for the point-to-point network and ``nCsma`` "extra" nodes. 

What we want to get at is the last of the "extra" nodes.  The zeroth entry of

the ``csmaNodes`` container will be the point-to-point node.  The easy

way to think of this, then, is if we create one "extra" CSMA node, then it

will be at index one of the ``csmaNodes`` container.  By induction,

if we create ``nCsma`` "extra" nodes the last one will be at index 

``nCsma``.  You see this exhibited in the ``Get`` of the first line of 

code.

The client application is set up exactly as we did in the ``first.cc``

example script.  Again, we provide required ``Attributes`` to the 

``UdpEchoClientHelper`` in the constructor (in this case the remote address

and port).  We tell the client to send packets to the server we just installed

on the last of the "extra" CSMA nodes.  We install the client on the 

leftmost point-to-point node seen in the topology illustration.

::

  UdpEchoClientHelper echoClient (csmaInterfaces.GetAddress (nCsma), 9);

  echoClient.SetAttribute ("MaxPackets", UintegerValue (1));

  echoClient.SetAttribute ("Interval", TimeValue (Seconds (1.)));

  echoClient.SetAttribute ("PacketSize", UintegerValue (1024));

  ApplicationContainer clientApps = echoClient.Install (p2pNodes.Get (0));

  clientApps.Start (Seconds (2.0));

  clientApps.Stop (Seconds (10.0));

Since we have actually built an internetwork here, we need some form of 

internetwork routing.  |ns3| provides what we call global routing to

help you out.  Global routing takes advantage of the fact that the entire 

internetwork is accessible in the simulation and runs through the all of the

nodes created for the simulation --- it does the hard work of setting up routing 

for you without having to configure routers.

Basically, what happens is that each node behaves as if it were an OSPF router

that communicates instantly and magically with all other routers behind the

scenes.  Each node generates link advertisements and communicates them 

directly to a global route manager which uses this global information to 

construct the routing tables for each node.  Setting up this form of routing

is a one-liner:

::

  Ipv4GlobalRoutingHelper::PopulateRoutingTables ();

Next we enable pcap tracing.  The first line of code to enable pcap tracing 

in the point-to-point helper should be familiar to you by now.  The second

line enables pcap tracing in the CSMA helper and there is an extra parameter

you haven't encountered yet.

::

  pointToPoint.EnablePcapAll ("second");

  csma.EnablePcap ("second", csmaDevices.Get (1), true);

The CSMA network is a multi-point-to-point network.  This means that there 

can (and are in this case) multiple endpoints on a shared medium.  Each of 

these endpoints has a net device associated with it.  There are two basic

alternatives to gathering trace information from such a network.  One way 

is to create a trace file for each net device and store only the packets

that are emitted or consumed by that net device.  Another way is to pick 

one of the devices and place it in promiscuous mode.  That single device

then "sniffs" the network for all packets and stores them in a single

pcap file.  This is how ``tcpdump``, for example, works.  That final 

parameter tells the CSMA helper whether or not to arrange to capture 

packets in promiscuous mode.  

In this example, we are going to select one of the devices on the CSMA

network and ask it to perform a promiscuous sniff of the network, thereby

emulating what ``tcpdump`` would do.  If you were on a Linux machine

you might do something like ``tcpdump -i eth0`` to get the trace.  

In this case, we specify the device using ``csmaDevices.Get(1)``, 

which selects the first device in the container.  Setting the final

parameter to true enables promiscuous captures.

The last section of code just runs and cleans up the simulation just like

the ``first.cc`` example.

::

    Simulator::Run ();

    Simulator::Destroy ();

    return 0;

  }

In order to run this example, copy the ``second.cc`` example script into 

the scratch directory and use waf to build just as you did with

the ``first.cc`` example.  If you are in the top-level directory of the

repository you just type,

::

  cp examples/tutorial/second.cc scratch/mysecond.cc

  ./waf

Warning:  We use the file ``second.cc`` as one of our regression tests to

verify that it works exactly as we think it should in order to make your

tutorial experience a positive one.  This means that an executable named 

``second`` already exists in the project.  To avoid any confusion

about what you are executing, please do the renaming to ``mysecond.cc``

suggested above.

If you are following the tutorial religiously (you are, aren't you) you will

still have the NS_LOG variable set, so go ahead and clear that variable and

run the program.

::

  export NS_LOG=

  ./waf --run scratch/mysecond

Since we have set up the UDP echo applications to log just as we did in 

``first.cc``, you will see similar output when you run the script.

::

  Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'

  Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'

  'build' finished successfully (0.415s)

  Sent 1024 bytes to 10.1.2.4

  Received 1024 bytes from 10.1.1.1

  Received 1024 bytes from 10.1.2.4

Recall that the first message, "``Sent 1024 bytes to 10.1.2.4``," is the 

UDP echo client sending a packet to the server.  In this case, the server

is on a different network (10.1.2.0).  The second message, "``Received 1024 

bytes from 10.1.1.1``," is from the UDP echo server, generated when it receives

the echo packet.  The final message, "``Received 1024 bytes from 10.1.2.4``,"

is from the echo client, indicating that it has received its echo back from

the server.

If you now go and look in the top level directory, you will find three trace 

files:

::

  second-0-0.pcap  second-1-0.pcap  second-2-0.pcap

Let's take a moment to look at the naming of these files.  They all have the 

same form, ``<name>-<node>-<device>.pcap``.  For example, the first file

in the listing is ``second-0-0.pcap`` which is the pcap trace from node 

zero, device zero.  This is the point-to-point net device on node zero.  The 

file ``second-1-0.pcap`` is the pcap trace for device zero on node one,

also a point-to-point net device; and the file ``second-2-0.pcap`` is the

pcap trace for device zero on node two.

If you refer back to the topology illustration at the start of the section, 

you will see that node zero is the leftmost node of the point-to-point link

and node one is the node that has both a point-to-point device and a CSMA 

device.  You will see that node two is the first "extra" node on the CSMA

network and its device zero was selected as the device to capture the 

promiscuous-mode trace.

Now, let's follow the echo packet through the internetwork.  First, do a 

tcpdump of the trace file for the leftmost point-to-point node --- node zero.

::

  tcpdump -nn -tt -r second-0-0.pcap

You should see the contents of the pcap file displayed:

::

  reading from file second-0-0.pcap, link-type PPP (PPP)

  2.000000 IP 10.1.1.1.49153 > 10.1.2.4.9: UDP, length 1024

  2.007602 IP 10.1.2.4.9 > 10.1.1.1.49153: UDP, length 1024

The first line of the dump indicates that the link type is PPP (point-to-point)

which we expect.  You then see the echo packet leaving node zero via the 

device associated with IP address 10.1.1.1 headed for IP address

10.1.2.4 (the rightmost CSMA node).  This packet will move over the 

point-to-point link and be received by the point-to-point net device on node 

one.  Let's take a look:

::

  tcpdump -nn -tt -r second-1-0.pcap

You should now see the pcap trace output of the other side of the point-to-point

link:

::

  reading from file second-1-0.pcap, link-type PPP (PPP)

  2.003686 IP 10.1.1.1.49153 > 10.1.2.4.9: UDP, length 1024

  2.003915 IP 10.1.2.4.9 > 10.1.1.1.49153: UDP, length 1024

Here we see that the link type is also PPP as we would expect.  You see the

packet from IP address 10.1.1.1 (that was sent at 2.000000 seconds) headed 

toward IP address 10.1.2.4 appear on this interface.  Now, internally to this 

node, the packet will be forwarded to the CSMA interface and we should see it 

pop out on that device headed for its ultimate destination.  

Remember that we selected node 2 as the promiscuous sniffer node for the CSMA

network so let's then look at second-2-0.pcap and see if its there.

::

  tcpdump -nn -tt -r second-2-0.pcap

You should now see the promiscuous dump of node two, device zero:

::

  reading from file second-2-0.pcap, link-type EN10MB (Ethernet)

  2.003696 arp who-has 10.1.2.4 (ff:ff:ff:ff:ff:ff) tell 10.1.2.1

  2.003707 arp reply 10.1.2.4 is-at 00:00:00:00:00:06

  2.003801 IP 10.1.1.1.49153 > 10.1.2.4.9: UDP, length 1024

  2.003811 arp who-has 10.1.2.1 (ff:ff:ff:ff:ff:ff) tell 10.1.2.4

  2.003822 arp reply 10.1.2.1 is-at 00:00:00:00:00:03

  2.003915 IP 10.1.2.4.9 > 10.1.1.1.49153: UDP, length 1024

As you can see, the link type is now "Ethernet".  Something new has appeared,

though.  The bus network needs ``ARP``, the Address Resolution Protocol.

Node one knows it needs to send the packet to IP address 10.1.2.4, but it

doesn't know the MAC address of the corresponding node.  It broadcasts on the

CSMA network (ff:ff:ff:ff:ff:ff) asking for the device that has IP address

10.1.2.4.  In this case, the rightmost node replies saying it is at MAC address

00:00:00:00:00:06.  Note that node two is not directly involved in this 

exchange, but is sniffing the network and reporting all of the traffic it sees.

This exchange is seen in the following lines,

::

  2.003696 arp who-has 10.1.2.4 (ff:ff:ff:ff:ff:ff) tell 10.1.2.1

  2.003707 arp reply 10.1.2.4 is-at 00:00:00:00:00:06

Then node one, device one goes ahead and sends the echo packet to the UDP echo

server at IP address 10.1.2.4. 

::

  2.003801 IP 10.1.1.1.49153 > 10.1.2.4.9: UDP, length 1024

The server receives the echo request and turns the packet around trying to send

it back to the source.  The server knows that this address is on another network

that it reaches via IP address 10.1.2.1.  This is because we initialized global

routing and it has figured all of this out for us.  But, the echo server node

doesn't know the MAC address of the first CSMA node, so it has to ARP for it

just like the first CSMA node had to do.

::

  2.003811 arp who-has 10.1.2.1 (ff:ff:ff:ff:ff:ff) tell 10.1.2.4

  2.003822 arp reply 10.1.2.1 is-at 00:00:00:00:00:03

The server then sends the echo back to the forwarding node.

::

  2.003915 IP 10.1.2.4.9 > 10.1.1.1.49153: UDP, length 1024

Looking back at the rightmost node of the point-to-point link,

::

  tcpdump -nn -tt -r second-1-0.pcap

You can now see the echoed packet coming back onto the point-to-point link as

the last line of the trace dump.

::

  reading from file second-1-0.pcap, link-type PPP (PPP)

  2.003686 IP 10.1.1.1.49153 > 10.1.2.4.9: UDP, length 1024

  2.003915 IP 10.1.2.4.9 > 10.1.1.1.49153: UDP, length 1024

Lastly, you can look back at the node that originated the echo

::

  tcpdump -nn -tt -r second-0-0.pcap

and see that the echoed packet arrives back at the source at 2.007602 seconds,

::

  reading from file second-0-0.pcap, link-type PPP (PPP)

  2.000000 IP 10.1.1.1.49153 > 10.1.2.4.9: UDP, length 1024

  2.007602 IP 10.1.2.4.9 > 10.1.1.1.49153: UDP, length 1024

Finally, recall that we added the ability to control the number of CSMA devices