blob: 05668610f15338ce5ce82d41987f0f0c955a41e7 [file] [log] [blame]
Alexander Afanasyev4d325162012-06-01 12:28:50 -07001.. ndnSIM: NS-3 based NDN simulator
2.. ============================================================
3
4.. .. toctree::
5.. :maxdepth: 2
6
7Introduction
8==============
9
10The ndnSIM is NS-3 module that implements Named Data Networking (NDN) communication model, the clean slate Internet design. ndnSIM is specially optimized for simulation purposes and has a cleaner and more extensible internal structure comparing to the existing NDN implementation (Project CCNx).
11
12Following the NDN architecture, ndnSIM is implemented as a new network-layer protocol model, which can run on top of any available link-layer protocol model (point-to-point, CSMA, wireless, etc.).
13
14.. note::
15 It will also be possible to run ndnSIM on top of network-layer (IPv4, IPv6) and transport-layer (TCP, UDP) protocols.
16 However, it is not yet implemented and patches are welcome.
17
18.. This flexibility allows ndnSIM to simulate scenarios of various homogeneous and heterogeneous networks (e.g., NDN-only, NDN-over-IP, etc.).
19
20The simulator is implemented in a modular fashion, using separate C++ classes to model behavior of each network-layer entity in NDN: pending Interest table (PIT), forwarding information base (FIB), content store, network and application interfaces, Interest forwarding strategies, etc.
21This modular structure allows any component to be easily modified or replaced with no or minimal impact on other components.
22In addition, the simulator provides an extensive collection of interfaces and helpers to perform detailed tracing behavior of every component, as well as NDN traffic flow.
23
24The wire format of Interest and Data packets follows the format of the existing `CCNx Project's NDN implementation`_ (CCNx Binary Encoding), allowing reuse of the existing traffic analysis tools, as well as driving simulations using real NDN traffic traces.
25
26.. _CCNx Project's NDN implementation: http://www.ccnx.org/
27
28Getting Started
29===============
30
31Portability
32------------
33
34ndnSIM has been successfully compiled and used under Ubuntu Linux 11.04 (stock gcc), Mac OS 10.6/10.7 (gcc-4.2 apple/llvm, macports gcc 4.6), FreeBSD 8.2 (requires gcc from ports - the stock gcc will not work!).
35
36Requirements
37-------------
38
391. ndnSIM requires the latest version of NS-3 simulator (as of May 31st, 2012, development branch of NS-3).
40
412. ndnSIM requires boost libraries:
42
43 * For Ubuntu::
44
45 sudo aptitude install libboost-all-dev
46
47 * For MacOS (macports)::
48
49 sudo port instal boost
50
513. Other NS-3 modules have additional dependencies. For example, in
52order to run `visualizer`_ module, the following should be installed:
53
54 * For Ubuntu::
55
56 sudo apt-get install python-dev python-pygraphviz python-kiwi
57 sudo apt-get install python-pygoocanvas python-gnome2
58 sudo apt-get install python-gnomedesktop python-rsvg ipython
59
60 * For MacOS (macports)::
61
62 sudo port install py27-pygraphviz py27-kiwi py27-goocanvas
63
64.. _visualizer: http://www.nsnam.org/wiki/index.php/PyViz
65
66Downloading ndnSIM source
67=========================
68
69Only ndnSIM
70--------------
71
72Download NS-3 simulator. For example::
73
74 hg clone http://code.nsnam.org/ns-3-allinone/ ns-3-all
75 cd ns-3-all
76 ./download.py
77
78ndnSIM source code should be placed in ``src/ndnSIM`` folder under NS-3 simulator source tree. For example::
79
80 cd ns-3-dev
81 git clone git@github.com:NDN-Routing/ndnSIM.git ns-3/src/ndnSIM
82
83After cloning, a number of patches need to be applied to the base NS-3 to make sure ndnSIM compiles and works::
84
85 find src/ndnSIM/patches/ -type f -print 0 | xargs -0 patch -p1
86
87
88Custom (unsupported) branch of NS-3
89-------------------------------------------
90
91Alternatively, it is possible to download a custom (unsupported) branch of NS-3 that contains all necessary patches and more::
92
93 mkdir ndnSIM
94 cd ndnSIM
95 git clone git@github.com:cawka/ns-3-dev-ndnSIM.git ns-3
96 git clone git@github.com:cawka/pybindgen.git pybindgen
97 git clone git@github.com:NDN-Routing/ndnSIM.git ns-3/src/ndnSIM
98
99The first command is to create a directory, which will contain everything NS-3 related. The bare minimum is just base NS-3 (the first clone above). The second clone gets a module necessary to build python bindings, which are necessary for the visualizer module. The third clone gets actual ndnSIM code and places it in src/ directory.
100
101There are quite a few modification to the base NS-3 code that are necessary to run ndnSIM, and the code is periodically synchronized with the official developer branch. Eventually, all the changes will be merged to the official branch, but for the time being, it is necessary to use the customized branch.
102
103Compiling and running ndnSIM
104============================
105
106ndnSIM uses standard NS-3 compilation procedure. For example::
107
108 cd <ns-3-folder>
109 ./waf configure --enable-examples
110 ./waf
111
112To run :doc:`sample ndnSIM simulations <examples>`::
113
114 ./waf --run=ccnx-simple
115
116or::
117
118 ./waf --run=ccnx-grid
119
120.. note::
121 Do not forget to configure and compile NS-3 in optimized mode (``./waf configure -d optimized``) in order to run actual simulations.
122
123Logging
124-----------------
125
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700126Almost every component in ndnSIM exports logging interface, so it is possible in debug compilation of simulator to track many details. For example, by enabling logging of :ndnsim:`CcnxFace` and :ndnsim:`CcnxConsumer` will show everything what happens on :ndnsim:`CcnxFace` and :ndnsim:`CcnxConsumer` classes::
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700127
128 NS_LOG=CcnxFace:CcnxConsumer ./waf --run=ccnx-simple
129
130Refer to the source code and NS-3 documentation to see what logging interfaces are available and about details how enable one or more logging interfaces.
131
132Documentation
133------------------------
134
135Overall structure of ndnSIM is described in our technical report.
136
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700137It is also possible to build doxygen documentation of ndnSIM API (in ``ns-3/doc/html/``), provided that ``doxygen`` and ``graphviz`` modules are installed on system::
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700138
139 ./waf doxygen
140
141
142A very short guide to the code
143==============================
144
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700145All the NDN related code is in ``ns-3/src/ndnSIM``
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700146
147+-----------------+---------------------------------------------------------------------+
148| Folder | Description |
149+=================+=====================================================================+
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700150| ``model/`` | implementation of NDN base: :ndnsim:`CcnxL3Protocol`, faces |
151| | (:ndnsim:`CcnxFace`, :ndnsim:`CcnxNetDeviceFace`, forwarding |
152| | :ndnsim:`CcnxLocalFace`), |
153| | strategies (:ndnsim:`CcnxForwardingStrategy`, |
154| | :ndnsim:`CcnxFloodingStrategy`, :ndnsim:`CcnxBestRouteStrategy`), |
155| | etc. |
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700156+-----------------+---------------------------------------------------------------------+
157| ``apps/`` | applications (in NS-3 sense) that can be installed on the nodes. |
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700158| | Right now we have one producer (:ndnsim:`CcnxProducer`) and a |
159| | collection of consumer (:ndnsim:`CcnxConsumerCbr`, |
160| | :ndnsim:`CcnxConsumerWindow`, |
161| | :ndnsim:`CcnxConsumerBatches`). See doxygen documentation or |
162| | source code for details |
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700163+-----------------+---------------------------------------------------------------------+
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700164| ``helper/`` | a number of :doc:`useful helpers <helpers>` |
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700165+-----------------+---------------------------------------------------------------------+
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700166| ``examples/`` | contain :doc:`several example scenarios <examples>` |
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700167+-----------------+---------------------------------------------------------------------+
168| ``utils/`` | helper classes |
169+-----------------+---------------------------------------------------------------------+
170| ``plugins/`` | a number of plugins that may be helpful to run simulation scenarios |
171+-----------------+---------------------------------------------------------------------+
172
173
174.. Indices and tables
175.. ==================
176
177.. * :ref:`genindex`
178.. * :ref:`modindex`
179.. * :ref:`search`
180