blob: 32f9f4ed9061e3e3dedaccded0b4e292d5ce0384 [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
Xinyu Mafc8956c2019-04-08 23:17:52 -070013A new release of `NS-3 based Named Data Networking (NDN) simulator <https://ndnsim.net/current/>`__
Alexander Afanasyev5dee3612015-08-25 16:09:04 -070014went through a number of extensive refactoring and rewriting. The key new features of the
15new version:
16
Xinyu Mafc8956c2019-04-08 23:17:52 -070017- Packet format changed to the `NDN packet format <https://named-data.net/doc/ndn-tlv/>`_
Alexander Afanasyev5dee3612015-08-25 16:09:04 -070018
19- ndnSIM uses implementation of basic NDN primitives from
20 `ndn-cxx library (NDN C++ library with eXperimental eXtensions)
Xinyu Mafc8956c2019-04-08 23:17:52 -070021 <https://named-data.net/doc/ndn-cxx/>`_
Alexander Afanasyev5dee3612015-08-25 16:09:04 -070022
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080023- All NDN forwarding and management is implemented directly using source code of `Named
Xinyu Mafc8956c2019-04-08 23:17:52 -070024 Data Networking Forwarding Daemon (NFD) <https://named-data.net/doc/NFD/>`_
Alexander Afanasyev5dee3612015-08-25 16:09:04 -070025
Spyridon Mastorakisaf09eac2018-02-22 11:25:26 -080026- It is possible to :doc:`simulate some real applications <guide-to-simulate-real-apps>`
Alexander Afanasyev5dee3612015-08-25 16:09:04 -070027 written against ndn-cxx library
Alexander Afanasyev4d325162012-06-01 12:28:50 -070028
29.. note::
Spyridon Mastorakisaf09eac2018-02-22 11:25:26 -080030 Please note that ndnSIM >= 2.0 has been through major refactoring and simulation scenario written for
31 ndnSIM 1.0 most likely would need to be changed to run on ndnSIM >= 2.0 platforms.
Alexander Afanasyev4d325162012-06-01 12:28:50 -070032
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080033Such integration with ndn-cxx and NFD ensures that the simulations are maximally realistic
34and can be reproduced in real environments with virtually no changes to the source code.
35In addition to that, any experiments with NDN forwarding (e.g., custom forwarding
36strategies) inside ndnSIM can be directly used within the real NFD implementation.
Alexander Afanasyev4d325162012-06-01 12:28:50 -070037
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080038Specifically, the simulator directly uses NFD implementations of :nfd:`pending Interest
Spyridon Mastorakisafad4592018-02-22 13:31:14 -080039table (PIT) <nfd::Pit>`, :nfd:`forwarding information base (FIB) <nfd::Fib>`, and
Spyridon Mastorakis5897c962015-08-31 15:37:18 -070040:nfd:`content store <nfd::cs::Cs>` data structures. In addition to that, ndnSIM allows
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080041experimentation with :ndnSIM:`ndnSIM-specific content store <ndn::ContentStore>` along
42with its cache replacement policies ported from the previous version of ndnSIM.
Alexander Afanasyev4d325162012-06-01 12:28:50 -070043
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080044ndnSIM is implemented as a new network-layer protocol model and can run on top of any
45available link-layer protocol model (point-to-point, CSMA, wireless, etc.).
46In addition, the simulator provides an extensive collection of interfaces and helpers to
47perform detailed tracing behavior of every component, as well as NDN traffic flow.
48
Alexander Afanasyev4d325162012-06-01 12:28:50 -070049
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080050More documentation
51------------------
Alexander Afanasyev4d325162012-06-01 12:28:50 -070052
Spyridon Mastorakisaf09eac2018-02-22 11:25:26 -080053Overall structure of ndnSIM is described in our paper and technical reports.
54
55**For ndnSIM >= 2.0:**
Spyridon Mastorakisa879e022017-10-16 17:12:14 -070056
Xinyu Mafc8956c2019-04-08 23:17:52 -070057- **S. Mastorakis, A. Afanasyev, and L. Zhang, "On the Evolution of ndnSIM: an Open-Source Simulator for NDN Experimentation," ACM SIGCOMM Computer Communication Review (CCR), July 2017** (`PDF <https://ccronline.sigcomm.org/wp-content/uploads/2017/08/sigcomm-ccr-final112-full-letter.pdf>`__, `BibTex <https://web.cs.ucla.edu/~mastorakis/bibtex-ndnsim>`__)
Spyridon Mastorakisacd5e1a2016-12-07 14:34:25 -080058
Xinyu Mafc8956c2019-04-08 23:17:52 -070059- **S. Mastorakis, A. Afanasyev, I. Moiseenko, and L. Zhang, "ndnSIM 2: An updated NDN simulator for NS-3," NDN, Technical Report NDN-0028, Revision 2, 2016** (`PDF <https://named-data.net/wp-content/uploads/2016/11/ndn-0028-2-ndnsim-v2.pdf>`__, `BibTex <https://users.cs.fiu.edu/~afanasyev/assets/bibtex/tr-mastorakis2016ndnsim.html>`__)
Spyridon Mastorakisacd5e1a2016-12-07 14:34:25 -080060
Spyridon Mastorakisaf09eac2018-02-22 11:25:26 -080061**For ndnSIM 1.0:**
62
Xinyu Mafc8956c2019-04-08 23:17:52 -070063- **A. Afanasyev, I. Moiseenko, and L. Zhang, "ndnSIM: NDN simulator for NS-3," NDN, Technical Report NDN-0005, 2012** (`PDF <https://users.cs.fiu.edu/~afanasyev/assets/bibtex/tr-afanasyev2012ndnsim.html>`__)
Alexander Afanasyev4d325162012-06-01 12:28:50 -070064
Alexander Afanasyev97fb44d2012-06-04 18:50:47 -070065`ndnSIM API documentation <doxygen/index.html>`_
Alexander Afanasyev4d325162012-06-01 12:28:50 -070066
Spyridon Mastorakisaf09eac2018-02-22 11:25:26 -080067Presentations on ndnSIM:
68
69- **S. Mastorakis, A. Afanasyev, and L. Zhang, "On the Evolution of ndnSIM: an Open-Source Ecosystem for NDN Experimentation", NDN Community Meeting (NDNcomm), Memphis, TN, March 2017** (`Slides <https://www.caida.org/workshops/ndn/1703/slides/ndn1703_smastorakis.pptx>`__)
70
71- **A. Afanasyev and others, Developing Simple Simulations with ndnSIM.” NDN Tutorial at ACM ICN 2016, Kyoto, Japan, Sep-2016** (`Slides <https://users.cs.fiu.edu/~afanasyev/assets/papers/talks-afanasyev2016ndn-tutorial-ndnsim.pdf>`__)
72
73- **S. Mastorakis, "ndnSIM: Current Status & Latest Advancements", 6th NDN Retreat, San Diego, CA, March 2016** (`Slides <https://www.caida.org/workshops/ndn/1603/slides/ndn1603_smastorakis2.pdf>`__)
74
75- **A. Afanasyev, J. Burke, P. Crowley, S. DiBenedetto, V. Jacobson, J. Thompson, B. Zhang, and L. Zhang, Named Data Networking. ndnSIM: a modular NDN simulator.” An Introduction to NDN and its Software Architecture Tutorial at 1st ACM Conference on Information-Centric Networking (ICN-2014), Sep-2014** (`Slides <https://users.cs.fiu.edu/~afanasyev/assets/papers/talks-afanasyev2014ndnsim.pptx>`__)
76
77- **A. Afanasyev, Tutorial for students: ndnSIM.” AsiaFI 2013 Summer School, Aug-2013** (`Slides <https://users.cs.fiu.edu/~afanasyev/assets/papers/talks-afanasyev2013ndnsim-tutorial.pptx>`__)
78
79- **A. Afanasyev, I. Moiseenko, and L. Zhang, ndnSIM: a modular NDN simulator. Introduction and Tutorial.” 3rd NDN retreat, Oct-2012** (`Slides <https://users.cs.fiu.edu/~afanasyev/assets/papers/talks-afanasyev2012ndnsim.pdf>`__)
80
81- **A. Afanasyev, I. Moiseenko, and L. Zhang, ndnSIM: a modular NDN simulator.” CCNxCon 2012, Sep-2012** (`Slides <https://users.cs.fiu.edu/~afanasyev/assets/papers/talks-ccnxcon-afanasyev2012ndnsim.pdf>`__)
82
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080083Also, you can `join our mailing list
Xinyu Mafc8956c2019-04-08 23:17:52 -070084<https://www.lists.cs.ucla.edu/mailman/listinfo/ndnsim>`_ to see and participate in
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080085discussions about ndnSIM implementation and simulations in general. Do not forget to
Xinyu Mafc8956c2019-04-08 23:17:52 -070086check mailling list `archives <https://www.lists.cs.ucla.edu/pipermail/ndnsim/>`_.
Alexander Afanasyev97fb44d2012-06-04 18:50:47 -070087
Alexander Afanasyev4d325162012-06-01 12:28:50 -070088
Alexander Afanasyev508269a2012-07-28 13:59:54 -070089Support
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080090-------
Alexander Afanasyev508269a2012-07-28 13:59:54 -070091
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080092The code of ndnSIM is in active development. Bug reports (issues) as well as new feature
93implementation are always welcome.
Alexander Afanasyev508269a2012-07-28 13:59:54 -070094
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080095To file a bug report, please use `NDN Redmine
Xinyu Mafc8956c2019-04-08 23:17:52 -070096<https://redmine.named-data.net/projects/ndnsim>`_.
Alexander Afanasyev508269a2012-07-28 13:59:54 -070097
98To create new feature, please fork the code and submit Pull Request on GitHub.
99
Xinyu Mafc8956c2019-04-08 23:17:52 -0700100And of course, `our mailing list <https://www.lists.cs.ucla.edu/mailman/listinfo/ndnsim>`_
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800101is the best way to communicate with and get support from ndnSIM team and other users of
102ndnSIM.
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700103
104A very short guide to the code
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700105------------------------------
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700106
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700107All the NDN related code is in ``ns-3/src/ndnSIM``
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700108
109+-----------------+---------------------------------------------------------------------+
110| Folder | Description |
111+=================+=====================================================================+
Alexander Afanasyevf6807a52012-08-10 18:11:43 -0700112| ``model/`` | implementation of NDN base: :ndnsim:`L3Protocol`, faces |
Spyridon Mastorakisacd5e1a2016-12-07 14:34:25 -0800113| | (:ndnsim:`Face`, :ndnsim:`NetDeviceTransport`, |
spirosmastorakisc09bb402016-10-28 19:16:58 -0700114| | :ndnsim:`AppLinkService`), |
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700115| | etc. |
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700116+-----------------+---------------------------------------------------------------------+
Alexander Afanasyev5dee3612015-08-25 16:09:04 -0700117| ``NFD/`` | submodule of `NDN Forwarding Daemon (NFD)`_ source code with few |
118| | modifications to make it compatible with the simulator |
119+-----------------+---------------------------------------------------------------------+
120| ``ndn-cxx/`` | submodule of `ndn-cxx library`_ source code with few |
121| | modifications to make it compatible with the simulator |
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800122+-----------------+---------------------------------------------------------------------+
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700123| ``apps/`` | applications (in NS-3 sense) that can be installed on the nodes. |
Alexander Afanasyevf6807a52012-08-10 18:11:43 -0700124| | Right now we have one producer (:ndnsim:`Producer`) and a |
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800125| | collection of consumer applications (:ndnsim:`ConsumerCbr`, |
126| | :ndnsim:`ConsumerWindow`, :ndnsim:`ConsumerBatches`, |
127| | :ndnsim:`ConsumerZipfMandelbrot`). See doxygen documentation or |
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700128| | source code for details |
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700129+-----------------+---------------------------------------------------------------------+
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800130| ``utils/`` | helper classes, including implementation of generalized data |
131| | structures, topology readers and tracers |
132+-----------------+---------------------------------------------------------------------+
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700133| ``helper/`` | a number of :doc:`useful helpers <helpers>` |
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700134+-----------------+---------------------------------------------------------------------+
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700135| ``examples/`` | contain :doc:`several example scenarios <examples>` |
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700136+-----------------+---------------------------------------------------------------------+
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800137
Xinyu Mafc8956c2019-04-08 23:17:52 -0700138.. _NDN Forwarding Daemon (NFD): https://named-data.net/doc/NFD/
Alexander Afanasyev5dee3612015-08-25 16:09:04 -0700139
Xinyu Mafc8956c2019-04-08 23:17:52 -0700140.. _ndn-cxx library: https://named-data.net/doc/ndn-cxx/
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700141
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700142Logging
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800143-------
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700144
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800145Almost every component in ndnSIM exports logging interface, so in debug compilation it is
146possible to track many internal details. For example, logging of :ndnsim:`Face` and
147:ndnsim:`Consumer` shows everything what happens in :ndnsim:`Face` and :ndnsim:`Consumer`
148classes::
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700149
Alexander Afanasyevfbbe13d2019-02-21 13:40:52 -0500150 NS_LOG=ndn.Consumer ./waf --run=ndn-simple
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700151
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800152Refer to the source code and NS-3 documentation to see what logging interfaces are
153available and about details how enable one or more logging interfaces.
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700154
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800155.. note::
156
157 Please remember that logging is enabled **only** in debug mode. When simulator is
158 compiled in optimized mode (``./waf configure -d optimized``), logging will be
159 completely disabled as it significantly slows down execution.
160
161.. note::
162
163 A list of log components available in the current version of NS-3 and ndnSIM is listed
164 `in this page <doxygen/LogComponentList.html>`_.