blob: 40bf4fd73515e6beb5b4e7861afe9b734b28e86f [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
Alexander Afanasyev5d79e682012-11-19 14:12:23 -08008============
Alexander Afanasyev4d325162012-06-01 12:28:50 -07009
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 Afanasyevf6807a52012-08-10 18:11:43 -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) <Pit>`, :ndnsim:`forwarding information base (FIB) <Fib>`, :ndnsim:`content store <ContentStore>`, :ndnsim:`network <NetDeviceFace>` and :ndnsim:`application <AppFace>` interfaces, :ndnsim:`Interest forwarding strategies <ForwardingStrategy>`, 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 Afanasyevf6807a52012-08-10 18:11:43 -070036 . | "Face" | | "Face" | .
37 . | "(AppFace)" | | "(NetDeviceFace)" | .
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 Afanasyevf6807a52012-08-10 18:11:43 -070045 . XX "(L3Protocol)" XX
Alexander Afanasyev97fb44d2012-06-04 18:50:47 -070046 . XX XX .
47 . XXXXXXXXXXXXXXXXXXXXXXXXXXXXX .
48 . ^ ^ ^ ^ .
49 . | | | | .
50 . +-------------------+ +---+ +---+ +------------+ .
51 . | | | | .
52 . v v v v .
53 . +-------------------+ +-------+ +-------+ +-------------+ .
Alexander Afanasyevf6807a52012-08-10 18:11:43 -070054 . | "ContentStore" | | PIT | | FIB | | "Forwarding"| .
55 . +-------------------+ +-------+ +-------+ | "Strategy" | .
Alexander Afanasyev97fb44d2012-06-04 18:50:47 -070056 . +-------------+ .
57 . .
58 ...............................................................................
59
60
Alexander Afanasyev4d325162012-06-01 12:28:50 -070061The 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.
62
63.. _CCNx Project's NDN implementation: http://www.ccnx.org/
64
65Getting Started
66===============
67
68Portability
69------------
70
Alexander Afanasyevf6807a52012-08-10 18:11:43 -070071ndnSIM has been successfully compiled and used under Ubuntu Linux 12.04 (stock gcc, boost 1.48), Mac OS 10.8 (gcc-4.2 apple/llvm, macports gcc 4.7, boost 1.49 or 1.50).
Alexander Afanasyev4d325162012-06-01 12:28:50 -070072
Alexander Afanasyev6dbacda2012-10-23 17:20:18 -070073.. _requirements:
74
Alexander Afanasyev4d325162012-06-01 12:28:50 -070075Requirements
76-------------
77
Alexander Afanasyev508269a2012-07-28 13:59:54 -0700781. 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 -070079
Alexander Afanasyev508269a2012-07-28 13:59:54 -0700802. Boost libraries should be installed on the system:
Alexander Afanasyev4d325162012-06-01 12:28:50 -070081
82 * For Ubuntu::
83
84 sudo aptitude install libboost-all-dev
85
86 * For MacOS (macports)::
87
88 sudo port instal boost
89
Alexander Afanasyev7099ffb2012-10-16 20:42:11 -070090.. note::
91 !!! If you do not have root permissions to install boost, you can install it in your home folder. However, you need to be make sure that `libboost_iostreams` library is successfully compiled and is installed. Please refer to :doc:`the following example <boost-custom-install>` for the hints how to successfully compile and install boost libraries on Ubuntu Linux.
92
93
Alexander Afanasyev508269a2012-07-28 13:59:54 -0700943. 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 -070095order to run `visualizer`_ module, the following should be installed:
96
97 * For Ubuntu::
98
99 sudo apt-get install python-dev python-pygraphviz python-kiwi
Alexander Afanasyev97fb44d2012-06-04 18:50:47 -0700100 sudo apt-get install python-pygoocanvas python-gnome2
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700101 sudo apt-get install python-gnomedesktop python-rsvg ipython
102
103 * For MacOS (macports)::
104
Alexander Afanasyev508269a2012-07-28 13:59:54 -0700105 sudo port install py27-pygraphviz py27-goocanvas
106
107.. py27-kiwi
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700108
109.. _visualizer: http://www.nsnam.org/wiki/index.php/PyViz
110
111Downloading ndnSIM source
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700112-------------------------
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700113
Alexander Afanasyev508269a2012-07-28 13:59:54 -0700114Download a custom branch of NS-3 that contains all necessary patches and more::
Alexander Afanasyevd4a59512012-06-22 10:14:55 -0700115
116 mkdir ndnSIM
117 cd ndnSIM
118 git clone git://github.com/cawka/ns-3-dev-ndnSIM.git ns-3
119 git clone git://github.com/cawka/pybindgen.git pybindgen
Alexander Afanasyev508269a2012-07-28 13:59:54 -0700120
121The 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.
122
123Finally, clone actual ndnSIM code and place it in src/ folder::
124
Alexander Afanasyevd4a59512012-06-22 10:14:55 -0700125 git clone git://github.com/NDN-Routing/ndnSIM.git ns-3/src/ndnSIM
126
Alexander Afanasyevd4a59512012-06-22 10:14:55 -0700127There 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.
128
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700129Compiling and running ndnSIM
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700130----------------------------
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700131
Alexander Afanasyev3cdda242012-09-04 16:26:46 -0700132ndnSIM uses standard NS-3 compilation procedure. Normally the following commands should be sufficient to configure and build ndnSIM with python bindings enabled::
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700133
134 cd <ns-3-folder>
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700135 ./waf configure --enable-examples --enable-ndn-plugins=topology,mobility
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700136 ./waf
137
Alexander Afanasyev3cdda242012-09-04 16:26:46 -0700138On MacOS (with macports), you may need to modify the configure command to use macports version of python::
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700139
Alexander Afanasyev3cdda242012-09-04 16:26:46 -0700140 cd <ns-3-folder>
141 ./waf configure --with-python=/opt/local/bin/python2.7 --enable-examples --enable-ndn-plugins=topology,mobility
142 ./waf
143
144Python bindings is an optional and not very stable feature of NS-3 simulator. It is possible to disable python bindings compilation either to speed up compilation or to avoid certain compilation errors (e.g., "Could not find a task generator for the name 'ns3-visualizer'")::
145
146 cd <ns-3-folder>
147 ./waf configure --disable-python --enable-examples --enable-ndn-plugins=topology,mobility
148 ./waf
149
150For more configuration options, please refer to ``./waf --help``.
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700151
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700152To run :doc:`sample ndnSIM simulations <examples>`::
153
Alexander Afanasyev3cdda242012-09-04 16:26:46 -0700154 ./waf --run=ndn-simple
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700155
156or::
157
Alexander Afanasyev3cdda242012-09-04 16:26:46 -0700158 ./waf --run=ndn-grid
159
160If you have compiled with python bindings, then you can try to run these simulations with visualizer::
161
162 ./waf --run=ndn-simple --vis
163
164or::
165
166 ./waf --run=ndn-grid --vis
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700167
168.. note::
169 Do not forget to configure and compile NS-3 in optimized mode (``./waf configure -d optimized``) in order to run actual simulations.
170
Alexander Afanasyev508269a2012-07-28 13:59:54 -0700171Additional compiling options
172++++++++++++++++++++++++++++
173
174ndnSIM 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::
175
176 ./waf configure --enable-ndn-plugins=topology,mobility
177
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700178
179Documentation
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700180=============
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700181
Alexander Afanasyev5b147e82012-06-22 10:39:46 -0700182Overall 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 -0700183
Alexander Afanasyev97fb44d2012-06-04 18:50:47 -0700184`ndnSIM API documentation <doxygen/index.html>`_
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700185
Alexander Afanasyev97fb44d2012-06-04 18:50:47 -0700186.. 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::
187
188.. ./waf doxygen
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700189
Alexander Afanasyev508269a2012-07-28 13:59:54 -0700190Support
191=======
192
193The code of ndnSIM is in active development. Bug reports (issues) as well as new feature implementation are always welcome.
194
195To file a bug report, please use `GitHub Issues <https://github.com/NDN-Routing/ndnSIM/issues>`_.
196
197To create new feature, please fork the code and submit Pull Request on GitHub.
198
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700199
200A very short guide to the code
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700201------------------------------
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700202
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700203All the NDN related code is in ``ns-3/src/ndnSIM``
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700204
205+-----------------+---------------------------------------------------------------------+
206| Folder | Description |
207+=================+=====================================================================+
Alexander Afanasyevf6807a52012-08-10 18:11:43 -0700208| ``model/`` | implementation of NDN base: :ndnsim:`L3Protocol`, faces |
209| | (:ndnsim:`Face`, :ndnsim:`NetDeviceFace`, forwarding |
210| | :ndnsim:`AppFace`), |
211| | strategies (:ndnsim:`ForwardingStrategy`, |
Alexander Afanasyevb8d14ad2012-08-09 13:19:37 -0700212| | :ndnsim:`Flooding`, :ndnsim:`SmartFlooding`, :ndnsim:`BestRoute`), |
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700213| | etc. |
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700214+-----------------+---------------------------------------------------------------------+
215| ``apps/`` | applications (in NS-3 sense) that can be installed on the nodes. |
Alexander Afanasyevf6807a52012-08-10 18:11:43 -0700216| | Right now we have one producer (:ndnsim:`Producer`) and a |
217| | collection of consumer (:ndnsim:`ConsumerCbr`, |
218| | :ndnsim:`ConsumerWindow`, |
219| | :ndnsim:`ConsumerBatches`). See doxygen documentation or |
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700220| | source code for details |
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700221+-----------------+---------------------------------------------------------------------+
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700222| ``helper/`` | a number of :doc:`useful helpers <helpers>` |
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700223+-----------------+---------------------------------------------------------------------+
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700224| ``examples/`` | contain :doc:`several example scenarios <examples>` |
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700225+-----------------+---------------------------------------------------------------------+
Alexander Afanasyev508269a2012-07-28 13:59:54 -0700226| ``utils/`` | helper classes, including implementation of generalized data |
227| | structures |
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700228+-----------------+---------------------------------------------------------------------+
229| ``plugins/`` | a number of plugins that may be helpful to run simulation scenarios |
230+-----------------+---------------------------------------------------------------------+
231
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700232Logging
233-----------------
234
Alexander Afanasyevf6807a52012-08-10 18:11:43 -0700235Almost 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:`Face` and :ndnsim:`Consumer` will show everything what happens on :ndnsim:`Face` and :ndnsim:`Consumer` classes::
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700236
Alexander Afanasyevf6807a52012-08-10 18:11:43 -0700237 NS_LOG=ndn.Face:ndn.Consumer ./waf --run=ndn-simple
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700238
239Refer 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 -0700240
241.. Indices and tables
242.. ==================
243
244.. * :ref:`genindex`
245.. * :ref:`modindex`
246.. * :ref:`search`
247