<?xml version="1.0"?>
<api>
  <query-continue>
    <allpages gapcontinue="Release_Process" />
  </query-continue>
  <query>
    <pages>
      <page pageid="1313" ns="0" title="Real World Application Integration">
        <revisions>
          <rev contentformat="text/x-wiki" contentmodel="wikitext" xml:space="preserve">{{TOC}}

= Project Background =
The goal of this proposed project is to develop frameworks and strategies that enable people to integrate already existing code into the simulator.  Depending on the application, this can be a straightforward or laborious process, but still should be preferable in many cases to rewriting these protocols from scratch, and hopefully this project can come up with techniques to make these ports even easier.

Here are some initial pointers to how this problem has been worked in the past:
* previous work on integrating Quagga protocols to ns-2 and GTNetS simulator 
** BGP++:  http://www.ece.gatech.edu/research/labs/MANIACS/BGP++/ 
** OSPFv3 on GTNetS at http://hipserver.mct.phantomworks.org/ietf/ospf : See the GTNetS Simulation tab
* the INETQuagga project of OMNeT++: http://www.omnetpp.org/pmwiki/index.php?n=Main.INETQuagga
* Naval Research Lab (NRL) has developed a number of nice open source abstraction libraries for ns-2.  One is called &quot;protolib&quot; and it allows for C-based routing daemons to run in ns-2, OPNET, and also as a userspace daemon.  There is a related one called &quot;Agent J&quot; that allows Java-based apps to run in ns-2 (or also on top of real sockets).  http://downloads.pf.itd.nrl.navy.mil/protolib/

= Gsoc Project =
Liu Jian(liujatp@gmail.com) started the gsoc project from April 2008.
== Abstract ==
The purpose of the project is to develop frameworks and strategies that enable people to integrate already existing code into the ns-3 simulator, it will be accomplished by integrating Quagga, a routing deamon which implement many useful routing protocols. The project will begin by learning experence that Quagga ever ported to INET simulator, then porting Quagga to ns3 by adding some patchings, through the porting job, summariced,documented and structured properly, a adaption layer or some methodologies for ns-3 will be implemented, through which other real world application will be easily ported by the next person.

== Project Plan ==
* looking at quagga to identify the system calls it use.(as functions like socket, time, signal,etc).

* implememt these function as simu_* in the ns-3-simu tree.

* porting quagga to ns3.

= Quagga porting =
== Status ==
* listed all system functions which quagga calls. there is about 30 funs of total 150 need to be implemented in ns-3-simu.
After investigation, there were 4 types of functions.  
  ''1,sockets:''
  accept;bind;close;connect;listen;recv;recvfrom;recvmsg;send;sendmsg;sendto;socket;
  getaddrinfo;freeaddrinfo;gai_strerror;getservbyname;getsockname;getsockopt;setsockopt,etc.
                 
  ''2,time:''
  ctime;gettimeofday;gmtime;localtime;mktime;strftime;time,etc.
             
  ''3,signal&amp;thread&amp;process:''
  exit;fork;getuid;geteuid;getpid;setpgid;setregid;setreuid;abort;kill;prctl;shutdown;
  sigaction;sigfillset;getgroups;setgroups;sysconf;waitpid,select(2),etc.
                                      
  ''4,others:'' 
  daemon;access;openlog;closelog;execv;getrusage;hostperror
  ZCMSG_FIRSTHDR(__cmsg_nxthdr),etc.

* to support ''socket(AF_NETLINK,XX,NETLINK_ROUTE)'', we need to implement a NetlinkSocket in NS3 which should support NETLINK_ROUTE protocol for quagga porting.
Through reading kernel code, libnl code[http://people.suug.ch/~tgr/libnl/] and RFC-3549[[ftp://ftp.rfc-editor.org/in-notes/rfc3549.txt]], the principle of netlink socket was basically clear. Now the draft implementation has been acommplished, which can exchange netlink route information between userspace and kernel space as the linux kernel did, but also need more testing.

Files were at my repo[http://code.nsnam.org/lj/quagga-porting/](not merged yet):
  src/node/netlink-socket.n/cc                                 
  src/node/netlink-socket-address.h/cc
  src/node/netlink-socket-factory.h/cc
  src/node/netlink-socket-helper.h/cc
  src/node/netlink-attribute.h/cc
  src/node/netlink-message.h/cc
  src/node/netlink-route-types.h(for NETLINK_ROUTE)
  src/node/netlink-message-route.h/cc
test files: 
  src/node/netlink-socket-test.cc
  example/simple-netlink-socket.cc

* testing NetlinkSocket(porting libnl to ns3)
libnl is an library using netlink socket, it provide user many brief programs to manage and operate route inforamtion and others. So porting libnl was suggested to make it run on top of ns-3-simu, and with some aims: testing NetlinkMessage seri/deseri operation; learing how the real-world netlink socket be used and improving my ns3 NetlinkSocket code.

now the porting was basically done and some libnl test programs about netlink-route has run successfully on top of ns-3-simu, as a real world application, it use the synchronous posix/sockets APIs and macro definitions from ns-3-simu/process to replace the real world system calls and macros, and let itself run in the ns3 simulate enviroment.

meanwhile, some simu_xxx functions has been implemented which should be supported for libnl, e.g. sendto/sendmsg/recvfrom/recvmsg. also setsockopt and getsockname was under working.
with the help of porting libnl, NetlinkSocket code improved a lot. 


* next: implement other simu_xxx functions(an part of ns-3-simu work)
started by simple server/client demo code[http://cs.ecs.baylor.edu/~donahoo/practical/CSockets/textcode.html]
running in ns-3-simu and test simu_x APIs.


* last:porting quagga to ns3&lt;may not reached&gt;
it was based on ns-3-simu/process module, when the essential simu_xxx functions were all implemented, the quagga can be ported and run on top of ns3 as libnl do.

== Detail Schedule ==
* ~-4.30 read and compile quagga source code, list simu_xxx sys-calls; 
* 5.5~5.9 read zebra codebase, get some view of the code structure and running mechanism.
* 5.12~5.19  read kerel code, libnl code, RFC3549, get some basic view about netlink socket
* 5.20~6.20 implement a draft netlink socket which support NETLINK_ROUTE protocol
* 6.23~6.30 ns3 internal testing for NetlinkSocket class at file netlink-socket-test.cc
* 7.1~7.11 porting libnl to ns-3-simu, at src/porting
* 7.14~7.18 testing libnl on top of ns3(mainly with NETLINK_ROUTE) and improve netlink socket code
* 7.21~7.27 improve NetlinkSocket code for support multicast mechanism.
* 7.28~8.15 porting libnl and quagga with elfloader
* 8.18~9.1 code review,clean and merge, documentation, etc.

== NetlinkSocket API ==
* '''NetlinkSocket''' class 
it was subclassed of Socket, it has the similar apis with the UDP/TCP socket.other related class:NetlinkSocketAddress/NetlinkSocketFactory/NetlinkSocketHelper 

this netlink socket should act as a kernel space code, it handle the message from the user space, then send message back to user space. Now The NetlinkSocket contains some private functions to do this kernel-like job, e.g. handlemessage() unicastmessage().. more functions at src/node/netlink-socket.h

* '''NetlinkMessage''' class
it represent the real world netlink message body. With Message header and payload, but for message serialization/desirialization, we designed the NetlinkMessage as subclass of Header class, which use the Header's seri/desi API to work. &lt;Ptr&gt;Packet can add/remove the message body as a header.

To be consistent between ns3 space and realworld application space, the serialize and desirialize was the very important part
based on Ns3 Header subclasses's API functions, this problem get easily fixed.

* '''MultipartNetlinkMessage''' class
To be compatible with dumping multipart netlinkmessges, MultipartNetlinkMessage class substitute NetlinkMessage's position, then NetlinkMessage become a member of it.

* payload messages
To support NETLINK_ROUTE, three types of paylod route message was provided: '''InterfaceAddressMessage'''(to RTM_XXX_ADDRESS),'''InterfaceInfoMessage'''(to RTM_XXX_LINK),'''RouteMessage'''(to RTM_XXX_ROUTE),  
besides of the no-prototol-specified '''NetlinkErrorMessge'''

* '''NetlinkAttribute'''class
it reperents of the payload messages's attributes, which has the TLV structure.


== porting libnl ==
libnl is an library using netlink socket, it provide user many brief programs to manage and operate route inforamtion and others. mathieu suggest me to port it and make it run on top of ns-3-simu, the goal is move libnl src file to ns3, let it run with the ns-3-simu apis, test the netlink socket to make it works well with the real world application.

Because libnl is an real-world application, i use the src/process simu module to do with it, which has the posix APIs and definetions, files at :
* src/porting
and the steps:
* define some macros to replace the real world definitions with SIMU_XXXX(at src/porting/porting-types.h) 
* replace the real world head files&quot;#include&lt;system-headfiles&gt;&quot; with simu head files &quot;#include&lt;simu_headfiles&gt;&quot;. 
* replace the system call xxx() with simu_xxx() in libnl source files. 
For the three steps, i added some simu_xxx() and SIMU_XXX the libnl used in process module , because the process module is also on developing stage by mathieu, many were unsupportable.

Libnl programs locate at src/porting/libnl/src/*.c, there were all real-world application. 
ns-3-simu/process module provide mechanism to run programs on top of ns3, so, for porting, where i create an program &quot;libnl-test&quot; (src/porting/libnl-test.cc) to run libnl at well defined ns3 Node, which has some simple network toplogy.

As for nl-addr-dump program, change the name ''main(int, char*[])'' to ''nl_addr_dump(int, char*[])'', then ns3 node can run it as an process.
 it run as:
 ./waf --shell;
 cd build/debug/src/porting
 ./libnl-test nl-addr-dump xml
then it dump the current node's interface address inforamtion through NS3 NetlinkSocket.

Now the implementd netlink socket can partly support NETLINK_ROUTE protocol, so the ported testing programs were all about this protocol.

there are 8 programs,and all run normally.
 nl_addr_dump, nl_link_dump, nl_route_dump, nl_addr_add, nl_addr_delete; nl_route_add, nl_route_delete, nl_route_get.


== porting zebra ==
Zebra, as a main deamo of quaaga, can run as an single program, so as a start, i step on porting this module to ns-3-simu.

As methieu implement ElfLoader class to load libc function dynamically, the previous function mapping method of porting was not used anymore.
So the steps were:
*build real world program with the option -fpie, -pie
*add libc function definition.
*add simu_xxx if necessary.

Adopt the great useful elfloader, the real world application can be easily run on top of ns-3 if all used libc function were defined.

At ns-test:lj/quagga-porting, my test program process-libnl can run libnl program at ns3 node. zebra's libc function need more support, continuing....

= About Quagga =
== basic knowledge ==
Quagga is a routing soute of 5 routing protocols(RIP,RIPng,OSPFv2,OSPFv3,BGP) based on Zebra, they can be run simutaneously or separately.Zebra layer that contains what is known as the &quot;Routing Information Base&quot; or RIB.  Zebra is responsible for maintaining the RIB and for writing routes from the RIB into the kernel forwarding table.

Quagga was planned to use multi-threaded mechanism when it runs with a kernel that supports multi-threads. There may be several protocol-specific routing daemons and zebra the kernel routing manager.The ''ripd'' daemon handles the RIP protocol, while ''ospfd'' is a daemon which supports OSPF version 2. ''bgpd'' supports the BGP-4 protocol. For changing the kernel routing table and for redistribution of routes between different routing protocols, there is a kernel routing table manager ''zebra'' daemon. Quagga system architecture, see here http://www.quagga.net/docs/docs-info.php#SEC9.

see more information here:http://www.quagga.net/docs/docs-info.php

== netlink socket introduction ==
Netlink socket is a special IPC used for transferring information between kernel and user-space processes. It provides a full-duplex communication link between the two by way of standard socket APIs for user-space processes and a special kernel API for kernel modules. Netlink socket uses the address family AF_NETLINK, as compared to AF_INET used by TCP/IP socket. Each netlink socket feature defines its own protocol type in the kernel header file include/linux/netlink.h. 

The following is a subset of features and their protocol types currently supported by the netlink socket: 
* NETLINK_ROUTE: communication channel between user-space routing dæmons, such as BGP, OSPF, RIP and kernel packet forwarding module. User-space routing dæmons update the kernel routing table through this netlink protocol type. 

* NETLINK_FIREWALL: receives packets sent by the IPv4 firewall code. 

* NETLINK_NFLOG: communication channel for the user-space iptable management tool and kernel-space Netfilter module. 

* NETLINK_ARPD: for managing the arp table from user space. 
Here, in quagga, '''Netlink scoket with NETLINK_ROUTE''' was used.
About netlink_route see ''man 7 rtnetlink''

Netlink socket provides a BSD socket-style API that can be well understood.The standard socket APIs—socket(), bind(),sendmsg(), recvmsg() and close()—can be used by user-space applications to access netlink socket. 
* ''socket(AF_NETLINK, int type, NETLINK_ROUTE)'': the type is either SOCK_RAW or SOCK_DGRAM, because netlink is a datagram-oriented service. 
* ''bind(fd, (struct sockaddr*)&amp;nladdr, sizeof(nladdr))'':The netlink address structure is '''''struct sockaddr_nl'''''.
* ''sendmsg (sock, &amp;msg, 0)''
* ''recvmsg (sock, &amp;msg, 0)''
* ''close (sock)''
the APIs are all standard calls, but the netlink socket requires its own message header as well -'''''struct nlmsghdr'''''.  A sending application must supply this header in each netlink message and a receiving application needs to allocate a buffer large enough to hold netlink message headers and message payloads. 

Detail information and example code see ''man 7 netlink''.

== some notes ==
''1'',   Firstly, if we donot care about how one of the protocols runs, we can get some idea about the main code-structure here, which would be useful for porting to ns3.                                                                               
* ''main structure''. _ _ _the main thread maintains thead_master, which contains all 'threads' triggered from event, timer, I/O, background,etc; when all initial work was finished, the whole application run as event-driven mode like below:
    ''main(){
        init_work();
        while(fetch_thread())
            call_thread();
    }''

* ''thread''. _ _ _Actually there were only one real-thread running at this time, it use the posix_signal hanlder functions, event functions of application-defined, many timer functions of the basic protocol-application , and ''select(2)''system all to  monitor I/O operations for multiplexing the events. the 'theads' mentioned above was not the common threads we commonly talk about, here it represent the all kinds of event-function defined above, the event-function, which was passed as function pointer and stored in thread-master, was called by sequence in main thread function depends on the different priority. the threads here has the _synchronous_ specific which was different from the threads in one real world application.

*''multithread mechanism in quagga''. _ _ _As a real-world application, quagga deal with posix-signal from system kernel, I/O events from IO devices, application-level events from kernel code and timer functions of maitaining the application noraml-running.it seems that these kinds of events were asynchronous to each other, which looks like a multithreads-application. But here in quagga, a creative mechanism was used to avoid multithreads. A threadmaster was maintained in main-thread, which store all kinds of events mentioned above in the form of sigmaster(discuss below), timer-list, io(read,write)list, event-list,etc.In the main loop, only one thread with the highest priority was called in each loop, which has some similarity with ns3 simulator's event-schedule model. (the priority: posix_signal events &gt; application-level events &gt; timer events &gt; IO events &gt; background-timer events). so the whole application runs as only one real thread avoiding multithreads-application resource sharing problem and system asynchronously controling problem.

*''signal mechanism in quagga''._ _ _As we know, quagga application can receive all signals from system and I/O, but it only defined some useful signal and trapped the others avoiding large system signal response. Usually,  posix signal can be triggered at anytime from kernel, and it use the kernel execution stack and context, which was asynchronous to the main thread. To avoid these asynchronism, here, in quagga, A ''sigmaster'' was used, which stored the signal information instead of calling handler function immediately when one posix signal was triggered in kernel. Then, the main_thread check out all triggered signals of last cycle from the ''segmaster'' and call their handler functions. So, the posix_signals were processed _synchronously_ in the whole application.

''2'',   started with Zebra.....</rev>
        </revisions>
      </page>
      <page pageid="1289" ns="0" title="Related Projects">
        <revisions>
          <rev contentformat="text/x-wiki" contentmodel="wikitext" xml:space="preserve">{{TOC}}

A number of external research projects and tools are using ns-3; below we list the ones that we know about.

Note:  There are a few projects related to ns-3 that are maintained along with ns-3 and are posted on our main web site [http://www.nsnam.org/overview/projects here].  These include 
1) Direct Code Execution, 
2) pybindgen, 
3) [[NetAnim]], and
4) bake.

== The LTE-EPC Network Simulator (LENA) project ==

A team of developers at CTTC (Nicola Baldo, Marco Miozzo, Manuel Requena, Jaume Nin) has [http://mailman.isi.edu/pipermail/ns-developers/2011-March/008734.html announced] the LENA (LTE/EPC Network simulAtor) project to be working in collaboration with Ubiquisys on an enhanced LTE module for ns-3.

Links:
* [http://www.ubiquisys.com/femtocell-media-press-releases-id-203.htm official press release from Ubiquisys' website]
* [http://iptechwiki.cttc.es/LTE-EPC_Network_Simulator_%28LENA%29 Wiki]
* [http://www.cttc.es/en/projects/private/project/lena.jsp official project page at CTTC]

== Satellite extensions for ns-3 ==

A project operated by Magister Solutions:  http://satellite-ns3.com/

== NEPI ==

NEPI is a lifecycle experiment manager for network experiments, including testbed-based, virtual machine-based, and simulation (ns-3)-based experiments, and combinations thereof.

Links:
* [http://nepi.inria.fr/ Project web site]

== Framework for Network Co-Simulation (FNCS) project ==

A team at Pacific Northwest National Laboratory has created a co-simulation framework involving power systems simulators (transmission and distribution systems) and ns-3.

Links:
* [https://www.youtube.com/watch?v=a4wtaqtXOOk video overview]
* [https://github.com/GridOPTICS/FNCS-Tutorial GitHub site]

== RapidNet ==

[http://netdb.cis.upenn.edu/rapidnet/index.html RapidNet] RapidNet is a development toolkit, based on ns-3, for declarative networking. 

== ndnSIM ==

The [http://ndnsim.net/ Named Data Networking simulator (ndnSIM)] simulator for name-based networking research is based on ns-3.

== N4C DTN project ==

The [http://www.n4c.eu/ N4C] project developed a DTN simulator combining LXC containers, ns-3 physical layer, and PyViz visualization.

Links:
* [http://www.springerlink.com/content/2677573v6u3l8151/?MUD=MP paper]
* [http://www.youtube.com/watch?v=bqq1jNVgRgc YouTube video]
* [http://info.n4c.eu/code/simulation-tools code]

== ns-3-Wireless-Planning ==

[http://code.google.com/p/ns3-wireless-planning/wiki/Tutorial ns-3-Wireless-Planning] integrates two powerful applications: Radio Mobile (radio-systems simulator) and ns-3.

== PhySim-Wifi ==

[http://dsn.tm.uni-karlsruhe.de/english/ns3-physim.php PhySim-Wifi] is a detailed and accurate implementation of the OFDM-based IEEE 802.11 standard, with higher fidelity at the physical layer than found in ns-3.

== NSF Frameworks for ns-3 project ==

A multi-year project funded by NSF to improve usability of ns-3.  Please see [[NSF_Frameworks]] page.

== Synchronized emulation (Slicetime) ==

The goal of the [http://www.comsys.rwth-aachen.de/research/projects/slicetime/ Slicetime] project is to enable large-scale network emulation features by synchronizing the execution of a network simulator with virtual machines hosting arbitrary networking software. 

== ns-2 Trace Toolkit ==

The [http://sourceforge.net/projects/ns2tracetoolkit/ ns-2 Trace Toolkit] was developed to analyze ns-2 traces, but also can be used for ns-3.

== WiMesh ==

The [http://wpage.unina.it/stavallo/WiMesh/ WiMesh tool] is a software tool for wireless mesh networks.   WiMesh allows to evaluate and compare the performances of a number of algorithms proposed in the literature to assign channel, transmission rate and power to the radios of the network nodes. WiMesh automatically sets up and runs an ns-3 simulation starting from the network topology as returned by the selected channel assignment algorithm.

== CROWD ==

CROWD is a European FP7 project that targets very dense heterogeneous wireless access networks and integrated wireless-wired backhaul networks - See more at: http://www.ict-crowd.eu/description.html#sthash.zuTl4dcx.dpuf.  Details on ns-3 integration can be found at this site:  http://www.ni.com/white-paper/52339/en/.

== VNS - Vehicular Networks Simulator ==

[http://www.dcc.fc.up.pt/~rjf/vns/ VNS] is a high-performance simulator for vehicular networks, developed by Ricardo Fernandes at DCC-FCUP and Instituto de Telecomunicações | Porto.   VNS can use ns-3 as an underlying network simulator.

== The CHIC Real-Time Testbed Project ==

[https://sourceforge.net/projects/chic/ CHIC] is a &quot;project based on NS-3 for modeling and real-time emulation of Coherent Heterogeneous Integrated Cellular networks on parallel computing systems.&quot;  Please see [http://eeweb.poly.edu/~srangan/testbeddocs/ford_thesis.pdf Russell Ford's thesis] for more information.  This is related to the CROWD project referenced above.

== SimGrid ==

[http://simgrid.gforge.inria.fr/ SimGrid] is a simulator to study the behavior of large-scale distributed systems such as Grids, Clouds, HPC or P2P systems.  SimGrid is a flow-based simulator but can alternatively use ns-3 (packet-level simulator) as its underlying network simulator; see [http://simgrid.gforge.inria.fr/simgrid/3.13/doc/pls.html this link].

== Modeler and Nephel3.com by 4-Layer Simulations LLC ==

[http://4-layer.com/ 4-Layer] provides commercial tools and services for ns-3 simulation.  The 4Layer Modeler tool is a graphical tool for constructing network models that can be simulated using ns-3. The Nephel3.com service takes a model as input and generates an ns-3 &quot;main&quot; program as output. The 4Layer Modeler tool is licensed and not open source. The backend code of the Nephel3 service is not distributed and not open source.  These developments were
presented in a [https://www.nsnam.org/workshops/wns3-2016/posters/Conway-poster.pdf poster/demo] at the [https://www.nsnam.org/overview/wns3/wns3-2016/accepted-posters-demos-short-talks/ 2016 ns-3 Workshop].

== ns3-lxc Linux Container project == 

This project, by Mike Albert, automates the process of ns-3 real-time script creation and Linux Container creation and linkage.  
* [https://github.com/buzz66boy/ns3-lxc/releases GitHub page]
* [https://groups.google.com/forum/#!topic/ns-3-users/9DUn4AODb7c announcement]

== Quantum Key Distribution Network Simulation Module ==

As reported by Miralem Mehic on the ns-developers mailing list (August 1, 2019): &quot;Quantum Key Distribution Network Simulation Module (QKDNetSim) is a unique tool that aims at enabling the publication of the new results and findings in a communication over a public channel of the Quantum Key Distribution (QKD) link. QKDNetSim uses the well-known Crypto++ open-source C++ class cryptographic library and well-tested code libraries of NS-3 simulator with minimal modifications to allow overlay network communication and the packet encapsulation.&quot;

* Corresponding author: Miralem Mehic &lt;miralem.mehic@ieee.org&gt;
* [http://www.qkdnetsim.info/ project page]

== Other projects ==

* [http://vnt.disi.unitn.it/downloads.php VANET code from the University of Trento]
* [http://www.ict-itetris.eu/platform.htm iTetris]
* [https://wiki.ittc.ku.edu/resilinets/Tools ResiliNets]
* [http://redmine.eg.bucknell.edu/perrone/projects/framework Simulation Automation Framework for Experiments (SAFE)]
* [http://pf.itd.nrl.navy.mil/core/core-html/ns3.html CORE emulator]
* [https://github.com/Microsoft/Tocino Microsoft Tocino:  NS3 Extensions to Simulate Direct Network Topologies]

== Blogs and personal pages about ns-3 ==

* [http://gicl.cs.drexel.edu/people/tjkopena/wiki/pmwiki.php?n=NS3.NS3 Joseph Kopena's ns-3 wiki]
* [http://www.eg.bucknell.edu/~perrone/tag/ns-3/ Felipe Perrone's blog]
* [http://eugen.dedu.free.fr/index.html#teaching Eugen Dedu's tutorial (in french)]</rev>
        </revisions>
      </page>
    </pages>
  </query>
</api>