| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
In this section we are going to expand our mastery of ns-3 network
devices and channels to cover an example of a bus network. Ns-3
provides a net device and channel we call CSMA (Carrier Sense Multiple Access).
The ns-3 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 ns-3 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 ns-3 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. ns-3 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
in the simulation by command line argument. You can change this argument in
the same way as when we looked at changing the number of packets echoed in the
first.cc example. Try running the program with the number of “extra”
devices set to four:
./waf --run "scratch/mysecond --nCsma=4"
You should now see,
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.405s) Sent 1024 bytes to 10.1.2.5 Received 1024 bytes from 10.1.1.1 Received 1024 bytes from 10.1.2.5
Notice that the echo server has now been relocated to the last of the CSMA nodes, which is 10.1.2.5 instead of the default case, 10.1.2.4.
It is possible that you may not be satisfied with a trace file generated by a bystander in the CSMA network. You may really want to get a trace from a single device and you may not be interested in any other traffic on the network. You can do this fairly easily/
Let’s take a look at scratch/mysecond.cc and add that code enabling us
to be more specific. ns-3 helpers provide methods that take a node
number and device number as parameters. Go ahead and replace the
EnablePcap calls with the calls below.
pointToPoint.EnablePcap ("second", p2pNodes.Get (0)->GetId (), 0);
csma.EnablePcap ("second", csmaNodes.Get (nCsma)->GetId (), 0, false);
csma.EnablePcap ("second", csmaNodes.Get (nCsma-1)->GetId (), 0, false);
We know that we want to create a pcap file with the base name "second" and we also know that the device of interest in both cases is going to be zero, so those parameters are not really interesting.
In order to get the node number, you have two choices: first, nodes are
numbered in a monotonically increasing fashion starting from zero in the
order in which you created them. One way to get a node number is to figure
this number out “manually” by contemplating the order of node creation.
If you take a look at the network topology illustration at the beginning of
the file, we did this for you and you can see that the last CSMA node is
going to be node number nCsma + 1. This approach can become
annoyingly difficult in larger simulations.
An alternate way, which we use here, is to realize that the
NodeContainers contain pointers to ns-3 Node Objects.
The Node Object has a method called GetId which will return that
node’s ID, which is the node number we seek. Let’s go take a look at the
Doxygen for the Node and locate that method, which is further down in
the ns-3 core code than we’ve seen so far; but sometimes you have to
search diligently for useful things.
Go to the Doxygen documentation for your release (recall that you can find it
on the project web site). You can get to the Node documentation by
looking through at the “Classes” tab and scrolling down the “Class List”
until you find ns3::Node. Select ns3::Node and you will be taken
to the documentation for the Node class. If you now scroll down to the
GetId method and select it, you will be taken to the detailed
documentation for the method. Using the GetId method can make
determining node numbers much easier in complex topologies.
Let’s clear the old trace files out of the top-level directory to avoid confusion about what is going on,
rm *.pcap rm *.tr
If you build the new script and run the simulation setting nCsma to 100,
./waf --run "scratch/mysecond --nCsma=100"
you will see the following output:
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.407s) Sent 1024 bytes to 10.1.2.101 Received 1024 bytes from 10.1.1.1 Received 1024 bytes from 10.1.2.101
Note that the echo server is now located at 10.1.2.101 which corresponds to having 100 “extra” CSMA nodes with the echo server on the last one. If you list the pcap files in the top level directory you will see,
second-0-0.pcap second-100-0.pcap second-101-0.pcap
The trace file second-0-0.pcap is the “leftmost” point-to-point device
which is the echo packet source. The file second-101-0.pcap corresponds
to the rightmost CSMA device which is where the echo server resides. You may
have noticed that the final parameter on the call to enable pcap tracing on the
echo server node was false. This means that the trace gathered on that node
was in non-promiscuous mode.
To illustrate the difference between promiscuous and non-promiscuous traces, we
also requested a non-promiscuous trace for the next-to-last node. Go ahead and
take a look at the tcpdump for second-100-0.pcap.
tcpdump -nn -tt -r second-100-0.pcap
You can now see that node 100 is really a bystander in the echo exchange. The only packets that it receives are the ARP requests which are broadcast to the entire CSMA network.
reading from file second-100-0.pcap, link-type EN10MB (Ethernet) 2.003696 arp who-has 10.1.2.101 (ff:ff:ff:ff:ff:ff) tell 10.1.2.1 2.003811 arp who-has 10.1.2.1 (ff:ff:ff:ff:ff:ff) tell 10.1.2.101
Now take a look at the tcpdump for second-101-0.pcap.
tcpdump -nn -tt -r second-101-0.pcap
You can now see that node 101 is really the participant in the echo exchange.
reading from file second-101-0.pcap, link-type EN10MB (Ethernet) 2.003696 arp who-has 10.1.2.101 (ff:ff:ff:ff:ff:ff) tell 10.1.2.1 2.003696 arp reply 10.1.2.101 is-at 00:00:00:00:00:67 2.003801 IP 10.1.1.1.49153 > 10.1.2.101.9: UDP, length 1024 2.003801 arp who-has 10.1.2.1 (ff:ff:ff:ff:ff:ff) tell 10.1.2.101 2.003822 arp reply 10.1.2.1 is-at 00:00:00:00:00:03 2.003822 IP 10.1.2.101.9 > 10.1.1.1.49153: UDP, length 1024
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] |
This document was generated on August 20, 2010 using texi2html 1.82.