blob: de72e7d7847276034290010d3376df820300d97a [file] [log] [blame]
Alexander Afanasyev4d325162012-06-01 12:28:50 -07001.. ndnSIM: NS-3 based NDN simulator
2.. ============================================================
3
Alexander Afanasyevf34fe562013-08-09 17:16:12 -07004============
Alexander Afanasyev4d325162012-06-01 12:28:50 -07005Introduction
Alexander Afanasyev5d79e682012-11-19 14:12:23 -08006============
Alexander Afanasyev4d325162012-06-01 12:28:50 -07007
Alexander Afanasyevfc9d9e12013-08-10 14:17:49 -07008.. sidebar:: ndnSIM components
9
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080010 .. image:: _static/ndnSIM-structure.*
Alexander Afanasyevfc9d9e12013-08-10 14:17:49 -070011 :width: 100%
12
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080013ndnSIM 2.0 is a new release of `NS-3 based Named Data Networking (NDN) simulator
14<http://ndnsim.net/1.0/>`_ that went through extensive refactoring and rewriting. The key
15new features of the new version:
Alexander Afanasyev4d325162012-06-01 12:28:50 -070016
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080017- ndnSIM no longer re-implements basic NDN primitives and directly uses implementation
18 from `ndn-cxx library (NDN C++ library with eXperimental eXtensions)
19 <http://named-data.net/doc/ndn-cxx/>`_.
20- All NDN forwarding and management is implemented directly using source code of `Named
21 Data Networking Forwarding Daemon (NFD) <http://named-data.net/doc/NFD/>`_
Alexander Afanasyev963621b2015-01-11 18:34:33 -080022- Packet format changed to the `NDN packet format <http://named-data.net/doc/ndn-tlv/>`_
Alexander Afanasyev4d325162012-06-01 12:28:50 -070023
24.. note::
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080025 Please note that ndnSIM 2.0 has major refactoring and simulation scenario written for
26 previous releases most likely would need to be changed to run on ndnSIM 2.0 platform.
Alexander Afanasyev4d325162012-06-01 12:28:50 -070027
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080028Such integration with ndn-cxx and NFD ensures that the simulations are maximally realistic
29and can be reproduced in real environments with virtually no changes to the source code.
30In addition to that, any experiments with NDN forwarding (e.g., custom forwarding
31strategies) inside ndnSIM can be directly used within the real NFD implementation.
Alexander Afanasyev4d325162012-06-01 12:28:50 -070032
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080033Specifically, the simulator directly uses NFD implementations of :nfd:`pending Interest
34table (PIT) <nfd::Pit>`, :nfd:`forwarding information base (FIB) <nfd::Fib>`, and
35:nfd:`content store <nfd::Cs>` data structures. In addition to that, ndnSIM allows
36experimentation with :ndnSIM:`ndnSIM-specific content store <ndn::ContentStore>` along
37with its cache replacement policies ported from the previous version of ndnSIM.
Alexander Afanasyev4d325162012-06-01 12:28:50 -070038
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080039ndnSIM is implemented as a new network-layer protocol model and can run on top of any
40available link-layer protocol model (point-to-point, CSMA, wireless, etc.).
41In addition, the simulator provides an extensive collection of interfaces and helpers to
42perform detailed tracing behavior of every component, as well as NDN traffic flow.
43
Alexander Afanasyev4d325162012-06-01 12:28:50 -070044
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080045More documentation
46------------------
Alexander Afanasyev4d325162012-06-01 12:28:50 -070047
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080048Overall structure of ndnSIM is described in our `technical report
49<http://lasr.cs.ucla.edu/afanasyev/data/files/Afanasyev/ndnSIM-TR.pdf>`_.
Alexander Afanasyev4d325162012-06-01 12:28:50 -070050
Alexander Afanasyev97fb44d2012-06-04 18:50:47 -070051`ndnSIM API documentation <doxygen/index.html>`_
Alexander Afanasyev4d325162012-06-01 12:28:50 -070052
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080053Also, you can `join our mailing list
54<http://www.lists.cs.ucla.edu/mailman/listinfo/ndnsim>`_ to see and participate in
55discussions about ndnSIM implementation and simulations in general. Do not forget to
56check mailling list `archives <http://www.lists.cs.ucla.edu/pipermail/ndnsim/>`_.
Alexander Afanasyev97fb44d2012-06-04 18:50:47 -070057
Alexander Afanasyev4d325162012-06-01 12:28:50 -070058
Alexander Afanasyev508269a2012-07-28 13:59:54 -070059Support
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080060-------
Alexander Afanasyev508269a2012-07-28 13:59:54 -070061
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080062The code of ndnSIM is in active development. Bug reports (issues) as well as new feature
63implementation are always welcome.
Alexander Afanasyev508269a2012-07-28 13:59:54 -070064
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080065To file a bug report, please use `NDN Redmine
66<http://redmine.named-data.net/projects/ndnsim>`_.
Alexander Afanasyev508269a2012-07-28 13:59:54 -070067
68To create new feature, please fork the code and submit Pull Request on GitHub.
69
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080070And of course, `our mailing list <http://www.lists.cs.ucla.edu/mailman/listinfo/ndnsim>`_
71is the best way to communicate with and get support from ndnSIM team and other users of
72ndnSIM.
Alexander Afanasyev4d325162012-06-01 12:28:50 -070073
74A very short guide to the code
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -070075------------------------------
Alexander Afanasyev4d325162012-06-01 12:28:50 -070076
Alexander Afanasyev6315ef72012-06-01 20:56:31 -070077All the NDN related code is in ``ns-3/src/ndnSIM``
Alexander Afanasyev4d325162012-06-01 12:28:50 -070078
79+-----------------+---------------------------------------------------------------------+
80| Folder | Description |
81+=================+=====================================================================+
Alexander Afanasyevf6807a52012-08-10 18:11:43 -070082| ``model/`` | implementation of NDN base: :ndnsim:`L3Protocol`, faces |
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080083| | (:ndnsim:`Face`, :ndnsim:`NetDeviceFace`, |
Alexander Afanasyevf6807a52012-08-10 18:11:43 -070084| | :ndnsim:`AppFace`), |
Alexander Afanasyev6315ef72012-06-01 20:56:31 -070085| | etc. |
Alexander Afanasyev4d325162012-06-01 12:28:50 -070086+-----------------+---------------------------------------------------------------------+
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080087| ``NFD/`` | contains the `NFD`_ source code with few modifications to make it |
88| | compatible with the simulator |
89+-----------------+---------------------------------------------------------------------+
Alexander Afanasyev4d325162012-06-01 12:28:50 -070090| ``apps/`` | applications (in NS-3 sense) that can be installed on the nodes. |
Alexander Afanasyevf6807a52012-08-10 18:11:43 -070091| | Right now we have one producer (:ndnsim:`Producer`) and a |
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080092| | collection of consumer applications (:ndnsim:`ConsumerCbr`, |
93| | :ndnsim:`ConsumerWindow`, :ndnsim:`ConsumerBatches`, |
94| | :ndnsim:`ConsumerZipfMandelbrot`). See doxygen documentation or |
Alexander Afanasyev6315ef72012-06-01 20:56:31 -070095| | source code for details |
Alexander Afanasyev4d325162012-06-01 12:28:50 -070096+-----------------+---------------------------------------------------------------------+
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080097| ``utils/`` | helper classes, including implementation of generalized data |
98| | structures, topology readers and tracers |
99+-----------------+---------------------------------------------------------------------+
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700100| ``helper/`` | a number of :doc:`useful helpers <helpers>` |
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700101+-----------------+---------------------------------------------------------------------+
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700102| ``examples/`` | contain :doc:`several example scenarios <examples>` |
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700103+-----------------+---------------------------------------------------------------------+
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800104
105.. _NFD: http://named-data.net/doc/NFD/
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700106
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700107Logging
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800108-------
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700109
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800110Almost every component in ndnSIM exports logging interface, so in debug compilation it is
111possible to track many internal details. For example, logging of :ndnsim:`Face` and
112:ndnsim:`Consumer` shows everything what happens in :ndnsim:`Face` and :ndnsim:`Consumer`
113classes::
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700114
Alexander Afanasyevf6807a52012-08-10 18:11:43 -0700115 NS_LOG=ndn.Face:ndn.Consumer ./waf --run=ndn-simple
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700116
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800117Refer to the source code and NS-3 documentation to see what logging interfaces are
118available and about details how enable one or more logging interfaces.
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700119
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800120.. note::
121
122 Please remember that logging is enabled **only** in debug mode. When simulator is
123 compiled in optimized mode (``./waf configure -d optimized``), logging will be
124 completely disabled as it significantly slows down execution.
125
126.. note::
127
128 A list of log components available in the current version of NS-3 and ndnSIM is listed
129 `in this page <doxygen/LogComponentList.html>`_.