blob: bcc3e3f0ee19c1783cb59553bee1cbe4e8b6925c [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
Alexander Afanasyev97fb44d2012-06-04 18:50:47 -070010The 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).
Alexander Afanasyev4d325162012-06-01 12:28:50 -070011
Alexander Afanasyev97fb44d2012-06-04 18:50:47 -070012Following 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.).
Alexander Afanasyev4d325162012-06-01 12:28:50 -070013
14.. note::
Alexander Afanasyev97fb44d2012-06-04 18:50:47 -070015 It will also be possible to run ndnSIM on top of network-layer (IPv4, IPv6) and transport-layer (TCP, UDP) protocols.
Alexander Afanasyev4d325162012-06-01 12:28:50 -070016 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
Alexander Afanasyev4a4ea602012-06-06 11:12:45 -070020The simulator is implemented in a modular fashion, using separate C++ classes to model behavior of each network-layer entity in NDN: :ndnsim:`pending Interest table (PIT) <CcnxPit>`, :ndnsim:`forwarding information base (FIB) <CcnxFib>`, :ndnsim:`content store <CcnxContentStore>`, :ndnsim:`network <CcnxNetDeviceFace>` and :ndnsim:`application <CcnxAppFace>` interfaces, :ndnsim:`Interest forwarding strategies <CcnxForwardingStrategy>`, etc.
Alexander Afanasyev4d325162012-06-01 12:28:50 -070021This 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
Alexander Afanasyev97fb44d2012-06-04 18:50:47 -070024
25.. aafig::
26 :aspect: 60
27 :scale: 120
28
29 +----------------+ +-----------+
30 | "Applications" | | NetDevice |
31 +----------------+ +-----------+
32 ^ ^
33 .................|......................................|......................
34 . v v .
35 . +------------------+ +----------------------+ .
36 . | "CcnxFace" | | "CcnxFace" | .
Alexander Afanasyev4a4ea602012-06-06 11:12:45 -070037 . | "(CcnxAppFace)" | | "(CcnxNetDeviceFace)"| .
Alexander Afanasyev97fb44d2012-06-04 18:50:47 -070038 . +------------------+ +----------------------+ .
39 . ^ ^ .
40 . | | .
41 . v v .
42 . XXXXXXXXXXXXXXXXXXXXXXXXXXXXX .
43 . XX XX .
44 . XX Core NDN protocol XX .
45 . XX "(CcnxL3Protocol)" XX
46 . XX XX .
47 . XXXXXXXXXXXXXXXXXXXXXXXXXXXXX .
48 . ^ ^ ^ ^ .
49 . | | | | .
50 . +-------------------+ +---+ +---+ +------------+ .
51 . | | | | .
52 . v v v v .
53 . +-------------------+ +-------+ +-------+ +-------------+ .
54 . | "CcnxContentStore"| | PIT | | FIB | | "Pluggable" | .
55 . +-------------------+ +-------+ +-------+ | "Forwarding"| .
56 . | "Strategy" | .
57 . +-------------+ .
58 . .
59 ...............................................................................
60
61
Alexander Afanasyev4d325162012-06-01 12:28:50 -070062The 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.
63
64.. _CCNx Project's NDN implementation: http://www.ccnx.org/
65
66Getting Started
67===============
68
69Portability
70------------
71
Alexander Afanasyev97fb44d2012-06-04 18:50:47 -070072ndnSIM 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!).
Alexander Afanasyev4d325162012-06-01 12:28:50 -070073
74Requirements
75-------------
76
Alexander Afanasyev97fb44d2012-06-04 18:50:47 -0700771. ndnSIM requires the latest version of NS-3 simulator (as of May 31st, 2012, development branch of NS-3).
Alexander Afanasyev4d325162012-06-01 12:28:50 -070078
792. ndnSIM requires boost libraries:
80
81 * For Ubuntu::
82
83 sudo aptitude install libboost-all-dev
84
85 * For MacOS (macports)::
86
87 sudo port instal boost
88
893. Other NS-3 modules have additional dependencies. For example, in
90order to run `visualizer`_ module, the following should be installed:
91
92 * For Ubuntu::
93
94 sudo apt-get install python-dev python-pygraphviz python-kiwi
Alexander Afanasyev97fb44d2012-06-04 18:50:47 -070095 sudo apt-get install python-pygoocanvas python-gnome2
Alexander Afanasyev4d325162012-06-01 12:28:50 -070096 sudo apt-get install python-gnomedesktop python-rsvg ipython
97
98 * For MacOS (macports)::
99
100 sudo port install py27-pygraphviz py27-kiwi py27-goocanvas
101
102.. _visualizer: http://www.nsnam.org/wiki/index.php/PyViz
103
104Downloading ndnSIM source
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700105-------------------------
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700106
107Only ndnSIM
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700108+++++++++++
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700109
110Download NS-3 simulator. For example::
111
112 hg clone http://code.nsnam.org/ns-3-allinone/ ns-3-all
113 cd ns-3-all
114 ./download.py
115
116ndnSIM source code should be placed in ``src/ndnSIM`` folder under NS-3 simulator source tree. For example::
117
118 cd ns-3-dev
Alexander Afanasyev98c9dbb2012-06-05 11:56:42 -0700119 git clone git://github.com/NDN-Routing/ndnSIM.git ns-3/src/ndnSIM
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700120
121After cloning, a number of patches need to be applied to the base NS-3 to make sure ndnSIM compiles and works::
122
123 find src/ndnSIM/patches/ -type f -print 0 | xargs -0 patch -p1
124
125
126Custom (unsupported) branch of NS-3
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700127+++++++++++++++++++++++++++++++++++
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700128
129Alternatively, it is possible to download a custom (unsupported) branch of NS-3 that contains all necessary patches and more::
130
131 mkdir ndnSIM
132 cd ndnSIM
Alexander Afanasyev98c9dbb2012-06-05 11:56:42 -0700133 git clone git://github.com/cawka/ns-3-dev-ndnSIM.git ns-3
134 git clone git://github.com/cawka/pybindgen.git pybindgen
135 git clone git://github.com/NDN-Routing/ndnSIM.git ns-3/src/ndnSIM
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700136
137The 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.
138
139There 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.
140
141Compiling and running ndnSIM
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700142----------------------------
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700143
144ndnSIM uses standard NS-3 compilation procedure. For example::
145
146 cd <ns-3-folder>
147 ./waf configure --enable-examples
148 ./waf
149
150To run :doc:`sample ndnSIM simulations <examples>`::
151
152 ./waf --run=ccnx-simple
153
154or::
155
156 ./waf --run=ccnx-grid
157
158.. note::
159 Do not forget to configure and compile NS-3 in optimized mode (``./waf configure -d optimized``) in order to run actual simulations.
160
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700161
162Documentation
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700163=============
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700164
165Overall structure of ndnSIM is described in our technical report.
166
Alexander Afanasyev97fb44d2012-06-04 18:50:47 -0700167`ndnSIM API documentation <doxygen/index.html>`_
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700168
Alexander Afanasyev97fb44d2012-06-04 18:50:47 -0700169.. It 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::
170
171.. ./waf doxygen
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700172
173
174A very short guide to the code
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700175------------------------------
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700176
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700177All the NDN related code is in ``ns-3/src/ndnSIM``
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700178
179+-----------------+---------------------------------------------------------------------+
180| Folder | Description |
181+=================+=====================================================================+
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700182| ``model/`` | implementation of NDN base: :ndnsim:`CcnxL3Protocol`, faces |
183| | (:ndnsim:`CcnxFace`, :ndnsim:`CcnxNetDeviceFace`, forwarding |
Alexander Afanasyev4a4ea602012-06-06 11:12:45 -0700184| | :ndnsim:`CcnxAppFace`), |
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700185| | strategies (:ndnsim:`CcnxForwardingStrategy`, |
186| | :ndnsim:`CcnxFloodingStrategy`, :ndnsim:`CcnxBestRouteStrategy`), |
187| | etc. |
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700188+-----------------+---------------------------------------------------------------------+
189| ``apps/`` | applications (in NS-3 sense) that can be installed on the nodes. |
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700190| | Right now we have one producer (:ndnsim:`CcnxProducer`) and a |
191| | collection of consumer (:ndnsim:`CcnxConsumerCbr`, |
192| | :ndnsim:`CcnxConsumerWindow`, |
193| | :ndnsim:`CcnxConsumerBatches`). See doxygen documentation or |
194| | source code for details |
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700195+-----------------+---------------------------------------------------------------------+
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700196| ``helper/`` | a number of :doc:`useful helpers <helpers>` |
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700197+-----------------+---------------------------------------------------------------------+
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700198| ``examples/`` | contain :doc:`several example scenarios <examples>` |
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700199+-----------------+---------------------------------------------------------------------+
200| ``utils/`` | helper classes |
201+-----------------+---------------------------------------------------------------------+
202| ``plugins/`` | a number of plugins that may be helpful to run simulation scenarios |
203+-----------------+---------------------------------------------------------------------+
204
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700205Logging
206-----------------
207
208Almost 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::
209
210 NS_LOG=CcnxFace:CcnxConsumer ./waf --run=ccnx-simple
211
212Refer 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.
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700213
214.. Indices and tables
215.. ==================
216
217.. * :ref:`genindex`
218.. * :ref:`modindex`
219.. * :ref:`search`
220