blob: 797bf53a12834090e27c07564664a6efec0c510a [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 Afanasyevb8d14ad2012-08-09 13:19:37 -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) <NdnPit>`, :ndnsim:`forwarding information base (FIB) <NdnFib>`, :ndnsim:`content store <NdnContentStore>`, :ndnsim:`network <NdnNetDeviceFace>` and :ndnsim:`application <NdnAppFace>` interfaces, :ndnsim:`Interest forwarding strategies <NdnForwardingStrategy>`, 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 . +------------------+ +----------------------+ .
Alexander Afanasyevb8d14ad2012-08-09 13:19:37 -070036 . | "NdnFace" | | "NdnFace" | .
37 . | "(NdnAppFace)" | | "(NdnNetDeviceFace)" | .
Alexander Afanasyev97fb44d2012-06-04 18:50:47 -070038 . +------------------+ +----------------------+ .
39 . ^ ^ .
40 . | | .
41 . v v .
42 . XXXXXXXXXXXXXXXXXXXXXXXXXXXXX .
43 . XX XX .
44 . XX Core NDN protocol XX .
Alexander Afanasyevb8d14ad2012-08-09 13:19:37 -070045 . XX "(NdnL3Protocol)" XX
Alexander Afanasyev97fb44d2012-06-04 18:50:47 -070046 . XX XX .
47 . XXXXXXXXXXXXXXXXXXXXXXXXXXXXX .
48 . ^ ^ ^ ^ .
49 . | | | | .
50 . +-------------------+ +---+ +---+ +------------+ .
51 . | | | | .
52 . v v v v .
53 . +-------------------+ +-------+ +-------+ +-------------+ .
Alexander Afanasyevb8d14ad2012-08-09 13:19:37 -070054 . | "NdnContentStore" | | PIT | | FIB | | "Pluggable" | .
Alexander Afanasyev97fb44d2012-06-04 18:50:47 -070055 . +-------------------+ +-------+ +-------+ | "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 Afanasyev508269a2012-07-28 13:59:54 -0700771. ndnSIM requires the customized version of NS-3 simulator (a number of patches required to make ndnSIM work with the latest development branch of NS-3).
Alexander Afanasyev4d325162012-06-01 12:28:50 -070078
Alexander Afanasyev508269a2012-07-28 13:59:54 -0700792. Boost libraries should be installed on the system:
Alexander Afanasyev4d325162012-06-01 12:28:50 -070080
81 * For Ubuntu::
82
83 sudo aptitude install libboost-all-dev
84
85 * For MacOS (macports)::
86
87 sudo port instal boost
88
Alexander Afanasyev508269a2012-07-28 13:59:54 -0700893. If you are planning to use other modules, like visualizer, a number of additional dependencies should be installed. For example, in
Alexander Afanasyev4d325162012-06-01 12:28:50 -070090order 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
Alexander Afanasyev508269a2012-07-28 13:59:54 -0700100 sudo port install py27-pygraphviz py27-goocanvas
101
102.. py27-kiwi
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700103
104.. _visualizer: http://www.nsnam.org/wiki/index.php/PyViz
105
106Downloading ndnSIM source
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700107-------------------------
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700108
Alexander Afanasyev508269a2012-07-28 13:59:54 -0700109Download a custom branch of NS-3 that contains all necessary patches and more::
Alexander Afanasyevd4a59512012-06-22 10:14:55 -0700110
111 mkdir ndnSIM
112 cd ndnSIM
113 git clone git://github.com/cawka/ns-3-dev-ndnSIM.git ns-3
114 git clone git://github.com/cawka/pybindgen.git pybindgen
Alexander Afanasyev508269a2012-07-28 13:59:54 -0700115
116The 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.
117
118Finally, clone actual ndnSIM code and place it in src/ folder::
119
Alexander Afanasyevd4a59512012-06-22 10:14:55 -0700120 git clone git://github.com/NDN-Routing/ndnSIM.git ns-3/src/ndnSIM
121
Alexander Afanasyevd4a59512012-06-22 10:14:55 -0700122There 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.
123
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700124Compiling and running ndnSIM
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700125----------------------------
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700126
127ndnSIM uses standard NS-3 compilation procedure. For example::
128
129 cd <ns-3-folder>
130 ./waf configure --enable-examples
131 ./waf
132
133To run :doc:`sample ndnSIM simulations <examples>`::
134
135 ./waf --run=ccnx-simple
136
137or::
138
139 ./waf --run=ccnx-grid
140
141.. note::
142 Do not forget to configure and compile NS-3 in optimized mode (``./waf configure -d optimized``) in order to run actual simulations.
143
Alexander Afanasyev508269a2012-07-28 13:59:54 -0700144Additional compiling options
145++++++++++++++++++++++++++++
146
147ndnSIM contains a number of NS-3 extensions that are not technically part of the ndnSIM. Right now there are two optional plugins---topology and mobility---which can be enabled using the following configuration option::
148
149 ./waf configure --enable-ndn-plugins=topology,mobility
150
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700151
152Documentation
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700153=============
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700154
Alexander Afanasyev5b147e82012-06-22 10:39:46 -0700155Overall structure of ndnSIM is described in our `technical report <http://lasr.cs.ucla.edu/afanasyev/data/files/Afanasyev/ndnSIM-TR.pdf>`_.
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700156
Alexander Afanasyev97fb44d2012-06-04 18:50:47 -0700157`ndnSIM API documentation <doxygen/index.html>`_
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700158
Alexander Afanasyev97fb44d2012-06-04 18:50:47 -0700159.. 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::
160
161.. ./waf doxygen
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700162
Alexander Afanasyev508269a2012-07-28 13:59:54 -0700163Support
164=======
165
166The code of ndnSIM is in active development. Bug reports (issues) as well as new feature implementation are always welcome.
167
168To file a bug report, please use `GitHub Issues <https://github.com/NDN-Routing/ndnSIM/issues>`_.
169
170To create new feature, please fork the code and submit Pull Request on GitHub.
171
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700172
173A very short guide to the code
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700174------------------------------
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700175
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700176All the NDN related code is in ``ns-3/src/ndnSIM``
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700177
178+-----------------+---------------------------------------------------------------------+
179| Folder | Description |
180+=================+=====================================================================+
Alexander Afanasyevb8d14ad2012-08-09 13:19:37 -0700181| ``model/`` | implementation of NDN base: :ndnsim:`NdnL3Protocol`, faces |
182| | (:ndnsim:`NdnFace`, :ndnsim:`NdnNetDeviceFace`, forwarding |
183| | :ndnsim:`NdnAppFace`), |
184| | strategies (:ndnsim:`NdnForwardingStrategy`, |
185| | :ndnsim:`Flooding`, :ndnsim:`SmartFlooding`, :ndnsim:`BestRoute`), |
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700186| | etc. |
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700187+-----------------+---------------------------------------------------------------------+
188| ``apps/`` | applications (in NS-3 sense) that can be installed on the nodes. |
Alexander Afanasyevb8d14ad2012-08-09 13:19:37 -0700189| | Right now we have one producer (:ndnsim:`NdnProducer`) and a |
190| | collection of consumer (:ndnsim:`NdnConsumerCbr`, |
191| | :ndnsim:`NdnConsumerWindow`, |
192| | :ndnsim:`NdnConsumerBatches`). See doxygen documentation or |
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700193| | source code for details |
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700194+-----------------+---------------------------------------------------------------------+
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700195| ``helper/`` | a number of :doc:`useful helpers <helpers>` |
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700196+-----------------+---------------------------------------------------------------------+
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700197| ``examples/`` | contain :doc:`several example scenarios <examples>` |
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700198+-----------------+---------------------------------------------------------------------+
Alexander Afanasyev508269a2012-07-28 13:59:54 -0700199| ``utils/`` | helper classes, including implementation of generalized data |
200| | structures |
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700201+-----------------+---------------------------------------------------------------------+
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
Alexander Afanasyevb8d14ad2012-08-09 13:19:37 -0700208Almost 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:`NdnFace` and :ndnsim:`NdnConsumer` will show everything what happens on :ndnsim:`NdnFace` and :ndnsim:`NdnConsumer` classes::
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700209
Alexander Afanasyevb8d14ad2012-08-09 13:19:37 -0700210 NS_LOG=NdnFace:NdnConsumer ./waf --run=ndn-simple
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700211
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