Simulate a Network Using NS-3

Pushpendu Kar and Sumit Goswami, IIT Kharagpur

Network Simulator 3 (NS-3) is a popular, flexible, fast, accurate, free and open source discrete event network simulator used to simulate network environments and protocols as a substitute of real implementation. It is primarily targeted for the use of research and education purposes. The software is intended as a replacement/advancement of currently popular Network Simulator 2 (NS-2). NS-3 is not compatible with NS-2. So network simulation codes written for NS-2 cannot run in this simulator. The NS-3 project has started in 2006 and the initial version -ver 3.1 was released in June, 2008 under open source licensing based on GNU GPLv2 compatibility. The current version of NS-3 is 3.13 and it is available for Linux, Windows/Cygwin, OS-X platforms. This simulator is implemented using C++ scripting with some Python interface. The simulation software is well documented with tutorial, manual, doxygen (help documents) and examples.

Basic Architecture of NS 3

Refer to http://tinyurl.com/6ue28sa to understand the basic architecture of NS-3. Here, an application within a node generate packets and forwarded to Net Devices through protocol stack. Then Net Devices send packets to other node(s) via channel. Net Devices of other nodes receive packets and forward to applications via protocol stack.

Getting Started

To start using NS-3, download it from the link, install and test it on a computer. It requires more than 350 MB of disk space for basic installation. A stepwise installation procedure for NS-3 with different options is as follows:

Step 1) Downloading NS-3: There are two ways of downloading NS-3 in Ubuntu which are as given:

(i) Downloading NS-3 Using Mercurial: Mercurial should be installed using 'Synaptic Package Manager' in Ubuntu. Then the following commands should be executed in the terminal window to download NS-3 using mercurial:

cd

mkdir repos

cd repos

hg clone http://code.nsnam.org/ns-3-allinone

./download.py -n ns-3-dev

(ii) Downloading NS-3 Using a Tarball: Besides Mercurial, this is another simpler process for downloading NS-3 which can be execute in the terminal window to download NS-3 .

cd

mkdir tarballs

cd tarballs

wget http://www.nsnam.org/releases/ns-allinone-3.10.tar.bz2

tar xjf ns-allinone-3.10.tar.bz2

Step 2) Building NS-3: There are two ways of building NS-3 after it has been successfully downloaded:

(i) Building NS-3 using build.py: To configure the downloaded NS-3 software for common usage, the following script has to be run from the directory in which NS-3 has been downloaded:

./build.py --enable-examples --enable-tests

Successful building will display following message in console.

'build' finished successfully (2m30.586s)

Modules built:

(ii) Building NS-3 using waf: Waf provides another way to configure and build NS-3 project using the following command:

./waf -d optimized --enable-examples --enable-tests configure3

Successful building will display following message in console.

'configure' finished successfully (2.870s)

Step 3) Testing NS-3: Successful installation of NS-3 distribution is tested by running the following script.

./test.py -c core

Successful test of NS-3 project will display following message in console.

92 of 92 tests passed (92 passed, 0 failed, 0 crashed, 0 valgrind errors)

Numeric values may vary from version to version of NS-3.

Development of an NS-3 Model

Model is a basic unit of simulator code which implements a protocol. A model is created by implementing a series of steps which are as mentioned:

1. Define requirements of the new model. This definition includes reusability of the model, dependency on other models, and functionality of the model.

2. Distribute the API header file for review and gather feedback from NS developers.

3. Review coding style of the new module and decide which compilation unit it resides in.

4. Write Constructor, empty function prototypes, key variables, Object/TypeId code.

5. Write small test programs.

6. Perform unit test on test programs.

7. Build core functions including logging and asserts.

8. Write unit tests for testing new module.

Simulating a Sample Network using NS-3

For the purpose of demonstration, we simulate a Carrier Sense Multiple Access (CSMA) LAN of five nodes. Then we implement client-server concept in this LAN. Here a specified node in the LAN performs as a server to consume packets and another node in the LAN performs as a client to send packets to the server. The code can be written in any standard editor. We had used 'eclipse' for writing the code.

/* Including header files */

#include "ns3/core-module.h"

#include "ns3/network-module.h"

#include "ns3/csma-module.h"

#include "ns3/internet-module.h"

#include "ns3/point-to-point-module.h"

#include "ns3/applications-module.h"

#include "ns3/ipv4-global-routing-helper.h"

#include "ns3/command-line.h"

/* Introduces the ns-3 namespace into the current(global) declarative region */

using namespace ns3;

/* Declares a logging component called 'Example' that allows to enable and disable console message logging by reference to the name. */

NS_LOG_COMPONENT_DEFINE ("Example");

/* Declaration of 'main' function */

int

main (int argc, char *argv<>)

/* Use of Command Line argument */

CommandLine cmd;

cmd.Parse(argc,argv);

/* Enabling debug logging at the INFO level for echo clients and servers */

LogComponentEnable ("UdpEchoClientApplication", LOG_LEVEL_INFO);

LogComponentEnable ("UdpEchoServerApplication", LOG_LEVEL_INFO);

/* The NodeContainer topology helper provides a convenient way to create,

manage and access any Node objects that we create in order to run a

simulation.*/

NodeContainer csmaNodes;

csmaNodes.Create (5);

/* CsmaHelper to create and connect CSMA devices to channel. */

CsmaHelper csma;

/* Setting channel attributes */

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

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

/* Create NetDeviceContainer to hold the devices created by CsmaHelper */

NetDeviceContainer csmaDevices;

/* Installing devices on CSMA Nodes */

csmaDevices = csma.Install (csmaNodes);

/* The InternetStackHelper is a topology helper that is to implement

internet stacks */

InternetStackHelper stack;

/* Installing internet stack on CSMA Nodes */

stack.Install (csmaNodes);

/* Topology helper to manage the allocation of IP Address */

Ipv4AddressHelper address;

/* Associate devices on nodes with IP Address */

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

/* Perform actual address assignment */

Ipv4InterfaceContainer csmaInterfaces;

csmaInterfaces = address.Assign (csmaDevices);

/* Object used to create actual server application */

UdpEchoServerHelper echoServer (9);

/* Installing server application on a CSMA Node */

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

/* Enabling Server Application */

serverApps.Start (Seconds (1.0));

/* Disabling Server Application */

serverApps.Stop (Seconds (50.0));

/* Object with server address and port number used to create actual client

application. */

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

/* Setting attributes */

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

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

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

/* Installing Client Application on a node */

ApplicationContainer clientApps = echoClient.Install (csmaNodes.Get (2));

/* Enabling client application */

clientApps.Start (Seconds (2.0));

/* Disabling client application */

clientApps.Stop (Seconds (50.0));

/* Setting up global routing */

Ipv4GlobalRoutingHelper::PopulateRoutingTables ();

/* Staring of simulation */

Simulator::Run ();

/* Ending of simulation */

Simulator::Destroy ();

return 0;

}

The file is saved with a .cc (for e.g. test.cc) extension and built and executed from the directory 'repos/ns-3-allinone/ns-3-dev'. The sequence of commands for building and executing the .cc file is:

./waf

./waf - -run scratch/test

scratch is the name of the directory where the .cc file has been stored. 'Scratch' directory is built by default under the path repos/ns-3-allinone/ns-3-dev. Alternate Directory may also be created. The output of the above command displays the simulation result on the console in text mode mentioning all the desired parameters. A more user friendly GUI based output can be obtained from the simulator by using NS-3 PyViz simulator visualize. This can be executed as

./waf - -run scratch/test - - vis, if Python Visualiser is already installed.

Conclusion

As the simulator is based on programming, complex network scenarios can be simulated using NS-3. A simulator helps to confirm the design parameters of a protocol and project the outcome of its execution. The simulations executed through this software are well accepted in the research community and has become a de facto standard for reporting simulation in Journals and Conferences of International repute.