2014.9.23 Dohyung Kim Computer network lab, mr.dhkim@gmail.com Introduction to NS3 2014.9.23 Dohyung Kim Computer network lab, mr.dhkim@gmail.com

Why simulate? Field tests are expensive Experiments can be hard to reproduce Collaboration is not easy

What is NS? NS is a discrete-event network simulator for internet system Protocol design, prototyping, multiple level of abstraction NS has a companion network animator called nam Has been called the nsnam project This graph is from cisco’s visual networking index.

NS history (~ns-2) 1995 1997 2000 Ns-1 (LBNL) - C++, Tcl - Event driven Core Ns-2 development - split object architecture - detailed TCP models - scheduler, queuing, links - routing, wireless, satellite - nam, topology generator Mainly integration of contributed code - Sensor network MAC and routing - SCTP and XCP - Wireless enhancement Tcl (tool command language)

Ns-2 impact Over 50% of ACM and IEEE network simulation papers from 200s0-2004 cite the use of ns-2 * Source: ACM Digital Library and IEEExplore searches

Skepticism abounds “...Tragedy of the Commons...” “For years, the community had to rely on simulators, which now seem a little dated, and it’s not clear who was convinced to adopt anything new based on ns2 simulations;” * Nick McKeown, VINI public review, ACM Sigcomm 2006 “...Tragedy of the Commons...” “...around 50% of the papers appeared to be... bogus...” “Who has ever validated NS2 code?” “To be honest, I'm still not sure whether I will use a simulation in a paper.” “...I will have a hard time accepting or advocating the use of NS-2 or any other simulation tool” * September 2005 archives of the e2e-interest mailing list

Trends Many researcher move away from simulation Experiments and testbed start to be preferred in major conference papers PlanetLab, OneLab, VINI, Emulab, ORBIT, WhyNet,.. Yet simulation tools proliferate Ns-2, OMNET++, NetSim, NCTUns, QualNet, OPNET, P2PSim, ONE, …

NS-3 A discrete event simulator Modular design / Open source Actively developed (contrast to NS-2) Developed in C++ / Python biding available Live visualizer Logging facility for debugging Tracing facility of getting output Direct Code Execution (DCE) Can be connected to a real network

Discrete Event Simulator Simulation time moves directly from event to event Schedule events to occur at specific simulation times A simulation scheduler orders the event execution Simulator execute events one by one Simulation stops at specific time or when events end

NS-3 Component NS-3 simulator Pre-processing Post-processing Traffic / topology generation Alignment with real systems (sockets, device driver interfaces) Post-processing NS-3 output file (trace file) analysis Throughput, delay, jitter, drop Various tracing system Graph xgraph, gnuplot

Installation www.nsnam.org Latest release ns-3.21 Installation manual Source download link https://www.nsnam.org/release/ns-allinone-3.21.tar.bz2 Documentation download link http://www.nsnam.org/ns-3-21/documentation Installation manual http://www.nsnam.org/wiki/Installation

How to Install Building Setting environment [user@eins ~/ns-allinone-3.21]# ./build.py Setting environment [user@eins~/ns-allinone-3.21/ns-3.21]# ./waf –d optimized configure [user@com ~/ns-allinone-3.21/ns-3.21]# ./waf -d debug --enable-examples --enable-tests configure [user@com ~/ns-allinone-3.21/ns-3.21]# ./waf [user@com ~/ns-allinone-3.15/ns-3.15]# ./test.py –c core

Workspace /ns-allinone-3.21/ns-3.21/scratch Run program only in the scratch folder Run program by the commands below ./waf --run scratch/example (or) ./waf --run example

NS-3 Basic Model Application Sockets-like API Protocol stack Node NetDevice Sockets-like API Channel Packet(s)‏

Core Classes Node Application No specific functionality Host(end system) in the Internet Install a net device and a network protocol Application A user program that generates some activity to be simulated UdpEchoServer, UdpEchoClient, OnOffApplication, BulkSendApplication, …

Core Classes Channel NetDevice Medium connected by nodes over which data flows Generally one-to-one mapped with NetDevice PointToPointchannel, CsmaChannel, WifiChannel, … NetDevice Like a specific kind of network cable and a hardware device Provides methods for managing connection to Node and channel PointToPointNetDevice, CsmaNetDevice, WifiNetDevice, …

Helper API A set of classes and methods that make common operation easier than using low level APIs Consists of Container objects Helper classes

Container A part of the ns-3 “helper API” Often simulation will need to do a number of identical actions to group of objects The helper API makes heavy use of containers of similar objects to which similar to identical operation can be performed

Helper classes Each function does a single operation on a “set of same objects” Provides simple ‘syntactical sugar’ to make simulation scripts look nicer and easier to read for network researchers

Container and Helper

Container and Helper example

Attribute Attributes are exported into a string-based namespace, with filesystem-like paths namespace supports regular expressions Nodes with NodeIds 1, 3, 4, 5, 8, 9, 10, 11: “/NodeList/[3-5]|[8-11]|1” Attributes also can be used without the paths e.g. “ns3::WifiPhy::TxGain”

Attribute A Config class allows users to manipulate the attributes e.g.: Set a default initial value for a variable Config::Set (“ns3::WifiPhy::TxGain”, DoubleValue (1.0)); Syntax also supports string values: Config::Set (“WifiPhy::TxGain”, StringValue (“1.0”)); AttributeValue IntegerValue, UintegerValue, DoubleValue, StringValue, …

Attribute Attribute namespace strings are used to describe paths through the namespace Refer to doxygen documents

NS-3 program structure

Simulation procedure 1. Turning on logging 2. Creating network topology 3. Creating application 4. Running simulator

Simulation procedure Turning on logging Define log component NS_LOG_COMPONENT_DEFINE ( name ) Enable log component LogComponentEnable ( name, level )

Logging Module Output messages from modules Useful when debugging NS_LOG environment variable NS_LOG_FUNCTION level information Verbosity level NS_LOG_ERROR — Log error messages; NS_LOG_WARN — Log warning messages; NS_LOG _EBUG — Log relatively rare debugging messages; NS_LOG_INFO — Log informational messages about program progress; NS_LOG_FUNCTION — Log a message describing each function called; NS_LOG_LOGIC – Log messages describing logical flow within a function; NS_LOG_ALL — Log everything. NS_LOG_UNCOND – Log the associated message unconditionally.

Command Line Arguments Change the simulation parameters using command line arguments First declare the command line parser in main function CommandLine cmd; cmd.Parse (argc, argv); Example ./waf --run "scratch/example1 –PrintHelp” ./waf –-run “scratch/example1 –PrintAttributes=ns3::PointToPointNetDevice” ./waf --run “scratch/example1 -ns3::PointToPointNetDevice::DataRate=5Mbps –ns3::PointToPointChannel::Delay=2ms”

Command Line Arguments When add your own hooks. cmd.AddValue in main function Example int main (int argc, char *argv[]) { uint32_t nPackets =1; CommandLine cmd; cmd.AddValue("nPackets", "Number of packets to echo", nPackets); Cmd.Parse (argc, argv); … echoClient.SetAttribute (“MaxPackets”, UintegerValue (nPackets)); ./waf --run “scratch/example1 –nPackets=2”

Simulation procedure Creating Network Topology Use Topology Helpers NodeContainer NodeContainer Ptr<Node> NodeContainer::Create (n) n: # of Nodes e.g.) NodeContainer nodes; nodes.Create (2);

CreateObject<> (); CreateObject<> is a wrapper for operator new. ns3::Object objects must be created on the heap using CreateObject<> (), which returns a smart pointer; e.g. Ptr<Node> rxNode = CreateObject<Node> ();

Create<> (); Create<> is simply a wrapper around operator new that correctly handles the reference counting system For objects deriving from class SimpleRefCount Ptr<Packet> p = Create<Packet> (data,size);

Simulation Procedure PointToPointHelper NetDeviceContainer void PointToPointHelper::SetDeviceAttribute (name, value) void PointToPointHelper::SetChannelAttribute (name, value) NetDeviceContainer PointToPointHelper::Install (NodeContainer c) NetDeviceContainer NetDeviceContainer Ptr<NetDevice> PointToPointHelper pointToPoint; pointToPoint.SetDeviceAttribute ("DataRate", StringValue ("5Mbps")); pointToPoint.SetChannelAttribute ("Delay", StringValue ("2ms")); NetDeviceContainer devices; devices = pointToPoint.Install (nodes);

Simulation Procedure UdpEchoServerHelper UdpEchoClientHelper UdpEchoServerHelper::UdpEchoServerHelper ( port ) ApplicationContainer UdpEchoServerHelper::Install (NodeContainer c ) UdpEchoClientHelper UdpEchoClientHelper::UdpEchoClientHelper ( ip, port ) void UdpEchoClientHelper::Setattribute ( name, value ) ApplicationContainer UdpEchoClientHelper::Install (NodeContainer c ) UdpEchoServerHelper echoServer (9); ApplicationContainer serverApps = echoServer.Install (nodes.Get (1)); serverApps.Start (Seconds (1.0)); serverApps.Stop (Seconds (10.0)); UdpEchoClientHelper echoClient (interfaces.GetAddress (1), 9); echoClient.SetAttribute ("MaxPackets", UintegerValue (1)); echoClient.SetAttribute ("Interval", TimeValue (Seconds (1.0))); echoClient.SetAttribute ("PacketSize", UintegerValue (1024)); ApplicationContainer clientApps = echoClient.Install (nodes.Get (0)); clientApps.Start (Seconds (2.0)); clientApps.Stop (Seconds (10.0));

Start Simulator Simulator::Run (); Destroy Simulator Simulator::Destroy ();

Simulation Example

Simple point-to-point link between two nodes and echo a single packet #include "ns3/core-module.h" #include "ns3/network-module.h" #include "ns3/internet-module.h" #include "ns3/point-to-point-module.h" #include "ns3/applications-module.h" using namespace ns3; NS_LOG_COMPONENT_DEFINE ("FirstScriptExample"); int main (int argc, char *argv[]) { LogComponentEnable("UdpEchoClientApplication", LOG_LEVEL_INFO); LogComponentEnable("UdpEchoServerApplication", LOG_LEVEL_INFO); NodeContainer nodes; nodes.Create (2); PointToPointHelper pointToPoint; pointToPoint.SetDeviceAttribute ("DataRate", StringValue ("5Mbps")); pointToPoint.SetChannelAttribute ("Delay", StringValue ("2ms")); NetDeviceContainer devices; devices = pointToPoint.Install (nodes);

InternetStackHelper stack; stack.Install (nodes); Ipv4AddressHelper address; address.SetBase ("10.1.1.0", "255.255.255.0"); Ipv4InterfaceContainer interfaces = address.Assign (devices); UdpEchoServerHelper echoServer (9); ApplicationContainer serverApps = echoServer.Install (nodes.Get (1)); serverApps.Start (Seconds (1.0)); serverApps.Stop (Seconds (10.0)); UdpEchoClientHelper echoClient (interfaces.GetAddress (1), 9); echoClient.SetAttribute ("MaxPackets", UintegerValue (1)); echoClient.SetAttribute ("Interval", TimeValue (Seconds (1.0))); echoClient.SetAttribute ("PacketSize", UintegerValue (1024)); ApplicationContainer clientApps = echoClient.Install (nodes.Get (0)); clientApps.Start (Seconds (2.0)); clientApps.Stop (Seconds (10.0)); Simulator::Run (); Simulator::Destroy (); return 0; }

Simulation Example ../ns-3.20] ./waf --run scratch/example1 Output At time 2s client sent 1024 bytes to 10.1.1.2 port 9 At time 2.00369s server received 1024 bytes from 10.1.1.1 port 49153 At time 2.00369s server sent 1024 bytes to 10.1.1.1 port 49153 At time 2.00737s client received 1024 bytes from 10.1.1.2 port 9

Tracing System Tracing is a structured form of simulation output

ASCII Tracing AsciiTraceHelper ascii; pointToPoint.EnableAsciiAll (ascii.CreateFileStream(“myfirst.tr”)); Simulator::Run (); Simulator::Destroy (); return 0; Output (myfirst.tr) + 2 /NodeList/0/DeviceList/0/$ns3::PointToPointNetDevice/TxQueue/Enqueue ns3::PppHeader (Point-to-Point Protocol: IP (0x0021)) ns3::Ipv4Header (tos 0x0 ttl 64 id 0 protocol 17 offset 0 flags [none] length: 1052 10.1.1.1 > 10.1.1.2) ns3::UdpHeader (length: 1032 49153 > 9) Payload (size=1024) - 2 /NodeList/0/DeviceList/0/$ns3::PointToPointNetDevice/TxQueue/Dequeue ns3::PppHeader (Point-to-Point Protocol: IP (0x0021)) ns3::Ipv4Header (tos 0x0 ttl 64 id 0 protocol 17 offset 0 flags [none] length: 1052 10.1.1.1 > 10.1.1.2) ns3::UdpHeader (length: 1032 49153 > 9) Payload (size=1024)

ASCII Tracing 00 + <operation – enqueue operation> 01 2 <simulation time> 02 /NodeList/0/DeviceList/0/$ns3::PointToPointNetDevice/TxQueue/Enqueue <trace source> 03 ns3::PppHeader ( 04 Point-to-Point Protocol: IP (0x0021)) <Link-layer header info> 05 ns3::Ipv4Header ( 06 tos 0x0 ttl 64 id 0 protocol 17 offset 0 flags [none] 07 length: 1052 10.1.1.1 > 10.1.1.2) <IP-header header info> 08 ns3::UdpHeader ( 09 length: 1032 49153 > 9) <TCP-header info> 10 Payload (size=1024) <payload info>

PCAP Tracing Generating packet trace file in .pcap format Can read the .pcap file with Wireshark or tcpdump http://www.wireshark.org/download.html Example pointToPoint.EnablePcapAll (“myfirst”); //Right before the call to Simulator::Run()

Tracing src/internet/model/tcp-tahoe.cc src/internet/model/tcp-tahoe.h

Tracing Callback Function Connect a trace source and trace sink Static void CwndChange (uint32_t oldCwnd, uint32_t newCwnd) { NS_LOG_UNCOND (Simulator::Now ().GetSeconds () << “\t” << newCwnd); } Static void RxDrop (Ptr<const Packet> p) { NS_LOG_UNCON (“RxDrop at” << Simulator::Now ().GetSeconds (); } Connect a trace source and trace sink ns3TcpSocket->TraceConnectWithoutContext (“CongestionWindow”, MakeCallback (&CwndChange)); devices.Get(1)->TraceConnectWithoutContext (“PhyRxDrop”, MakeCallback (&RxDrop));

Tracing Example Create a simple application #include <fstream> #include "ns3/core-module.h“ #include "ns3/network-module.h“ #include "ns3/internet-module.h“ #include "ns3/point-to-point-module.h“ #include "ns3/applications-module.h“ using namespace ns3; NS_LOG_COMPONENT_DEFINE ("FifthScriptExample"); class MyApp : public Application { public: MyApp (); virtual ~MyApp(); void Setup (Ptr<Socket> socket, Address address, uint32_t packetSize, uint32_t nPackets, DataRate dataRate); private: virtual void StartApplication (void); virtual void StopApplication (void); void ScheduleTx (void); void SendPacket (void); Ptr<Socket> m_socket; Address m_peer; uint32_t m_packetSize; uint32_t m_nPackets; DataRate m_dataRate; EventId m_sendEvent; bool m_running; uint32_t m_packetsSent;}; MyApp::MyApp () : m_socket (0), m_peer (), m_packetSize (0), m_nPackets (0), m_dataRate (0), m_sendEvent (), m_running (false), m_packetsSent (0) { } MyApp::~MyApp() m_socket = 0; void MyApp::Setup (Ptr<Socket> socket, Address address, uint32_t packetSize, uint32_t nPackets, DataRate dataRate){ m_socket = socket; m_peer = address; m_packetSize = packetSize; m_nPackets = nPackets; m_dataRate = dataRate; MyApp::StartApplication (void) m_running = true; m_packetsSent = 0; m_socket->Bind (); m_socket->Connect (m_peer); SendPacket (); Create a simple application

Tracing Example Trace sink void MyApp::StopApplication (void) { m_running = false; if (m_sendEvent.IsRunning ()) Simulator::Cancel (m_sendEvent); } if (m_socket) m_socket->Close (); MyApp::SendPacket (void) Ptr<Packet> packet = Create<Packet> (m_packetSize); m_socket->Send (packet); if (++m_packetsSent < m_nPackets) ScheduleTx (); MyApp::ScheduleTx (void) if (m_running) Time tNext (Seconds (m_packetSize * 8 / static_cast<double> (m_dataRate.GetBitRate ()))); m_sendEvent = Simulator::Schedule (tNext, &MyApp::SendPacket, this); static void CwndChange (uint32_t oldCwnd, uint32_t newCwnd) { NS_LOG_UNCOND (Simulator::Now ().GetSeconds () << "\t" << newCwnd); } RxDrop (Ptr<const Packet> p) NS_LOG_UNCOND ("RxDrop at " << Simulator::Now ().GetSeconds ()); int main (int argc, char *argv[]) NodeContainer nodes; nodes.Create (2); PointToPointHelper pointToPoint; pointToPoint.SetDeviceAttribute ("DataRate", StringValue ("5Mbps")); pointToPoint.SetChannelAttribute ("Delay", StringValue ("2ms")); NetDeviceContainer devices; devices = pointToPoint.Install (nodes); Ptr<RateErrorModel> em = CreateObjectWithAttributes<RateErrorModel> ( "RanVar", RandomVariableValue (UniformVariable (0., 1.)), "ErrorRate", DoubleValue (0.00001)); devices.Get (1)->SetAttribute ("ReceiveErrorModel", PointerValue (em)); InternetStackHelper stack; stack.Install (nodes); Ipv4AddressHelper address; address.SetBase ("10.1.1.0", "255.255.255.252"); Ipv4InterfaceContainer interfaces = address.Assign (devices);

Tracing Example TCP sink application uint16_t sinkPort = 8080; Address sinkAddress (InetSocketAddress(interfaces.GetAddress (1), sinkPort)); PacketSinkHelper packetSinkHelper ("ns3::TcpSocketFactory", InetSocketAddress (Ipv4Address::GetAny (), sinkPort)); ApplicationContainer sinkApps = packetSinkHelper.Install (nodes.Get (1)); sinkApps.Start (Seconds (0.)); sinkApps.Stop (Seconds (20.)); Ptr<Socket> ns3TcpSocket = Socket::CreateSocket (nodes.Get (0), TcpSocketFactory::GetTypeId ()); ns3TcpSocket->TraceConnectWithoutContext ("CongestionWindow", MakeCallback (&CwndChange)); Ptr<MyApp> app = CreateObject<MyApp> (); app->Setup (ns3TcpSocket, sinkAddress, 1040, 1000, DataRate ("1Mbps")); nodes.Get (0)->AddApplication (app); app->SetStartTime (Seconds (1.)); app->SetStopTime (Seconds (20.)); devices.Get (1)->TraceConnectWithoutContext("PhyRxDrop", MakeCallback (&RxDrop)); Simulator::Stop (Seconds(20)); Simulator::Run (); Simulator::Destroy (); return 0; } TCP sink application Connect Cwnd trace source and sink TCP application Connect RxDrop trace source and sink

First project Simulation Topology 100Mbps, 5ms 10 senders and 10 receivers 1 UDP flow and 9 TCP flows Simulation time: 60 seconds UDP sending rate is increased by 1 Mbps on every 5 seconds

Expected Simulation Result Trace with different queues Per-flow TCP Throughput Congestion window Routers’ queue size Queues DropTail RED

Submission program file (or files) Documents .cc (.h) Source code with line-by-line comments Simulation results