blob: 6f5ec4666ad76a1d62e07e3d38654ec997ea3fa8 [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
Alexander Afanasyevd4a59512012-06-22 10:14:55 -0700107(Recommended) Custom/unsupported branch of NS-3
108+++++++++++++++++++++++++++++++++++++++++++++++
109
110Alternatively, it is possible to download a custom (unsupported) branch of NS-3 that contains all necessary patches and more::
111
112 mkdir ndnSIM
113 cd ndnSIM
114 git clone git://github.com/cawka/ns-3-dev-ndnSIM.git ns-3
115 git clone git://github.com/cawka/pybindgen.git pybindgen
116 git clone git://github.com/NDN-Routing/ndnSIM.git ns-3/src/ndnSIM
117
118The 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.
119
120There 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.
121
122
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700123Only ndnSIM
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700124+++++++++++
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700125
126Download NS-3 simulator. For example::
127
128 hg clone http://code.nsnam.org/ns-3-allinone/ ns-3-all
129 cd ns-3-all
130 ./download.py
131
132ndnSIM source code should be placed in ``src/ndnSIM`` folder under NS-3 simulator source tree. For example::
133
134 cd ns-3-dev
Alexander Afanasyev39485d82012-06-08 17:51:47 -0700135 git clone gitolite@git.irl.cs.ucla.edu:ndn/ndnSIM.git ns-3/src/ndnSIM
136
137.. git clone git://github.com/NDN-Routing/ndnSIM.git ns-3/src/ndnSIM
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700138
139After cloning, a number of patches need to be applied to the base NS-3 to make sure ndnSIM compiles and works::
140
141 find src/ndnSIM/patches/ -type f -print 0 | xargs -0 patch -p1
142
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700143Compiling and running ndnSIM
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700144----------------------------
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700145
146ndnSIM uses standard NS-3 compilation procedure. For example::
147
148 cd <ns-3-folder>
149 ./waf configure --enable-examples
150 ./waf
151
152To run :doc:`sample ndnSIM simulations <examples>`::
153
154 ./waf --run=ccnx-simple
155
156or::
157
158 ./waf --run=ccnx-grid
159
160.. note::
161 Do not forget to configure and compile NS-3 in optimized mode (``./waf configure -d optimized``) in order to run actual simulations.
162
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700163
164Documentation
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700165=============
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700166
Alexander Afanasyev5b147e82012-06-22 10:39:46 -0700167Overall 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 -0700168
Alexander Afanasyev97fb44d2012-06-04 18:50:47 -0700169`ndnSIM API documentation <doxygen/index.html>`_
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700170
Alexander Afanasyev97fb44d2012-06-04 18:50:47 -0700171.. 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::
172
173.. ./waf doxygen
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700174
175
176A very short guide to the code
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700177------------------------------
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700178
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700179All the NDN related code is in ``ns-3/src/ndnSIM``
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700180
181+-----------------+---------------------------------------------------------------------+
182| Folder | Description |
183+=================+=====================================================================+
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700184| ``model/`` | implementation of NDN base: :ndnsim:`CcnxL3Protocol`, faces |
185| | (:ndnsim:`CcnxFace`, :ndnsim:`CcnxNetDeviceFace`, forwarding |
Alexander Afanasyev4a4ea602012-06-06 11:12:45 -0700186| | :ndnsim:`CcnxAppFace`), |
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700187| | strategies (:ndnsim:`CcnxForwardingStrategy`, |
188| | :ndnsim:`CcnxFloodingStrategy`, :ndnsim:`CcnxBestRouteStrategy`), |
189| | etc. |
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700190+-----------------+---------------------------------------------------------------------+
191| ``apps/`` | applications (in NS-3 sense) that can be installed on the nodes. |
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700192| | Right now we have one producer (:ndnsim:`CcnxProducer`) and a |
193| | collection of consumer (:ndnsim:`CcnxConsumerCbr`, |
194| | :ndnsim:`CcnxConsumerWindow`, |
195| | :ndnsim:`CcnxConsumerBatches`). See doxygen documentation or |
196| | source code for details |
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700197+-----------------+---------------------------------------------------------------------+
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700198| ``helper/`` | a number of :doc:`useful helpers <helpers>` |
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700199+-----------------+---------------------------------------------------------------------+
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700200| ``examples/`` | contain :doc:`several example scenarios <examples>` |
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700201+-----------------+---------------------------------------------------------------------+
202| ``utils/`` | helper classes |
203+-----------------+---------------------------------------------------------------------+
204| ``plugins/`` | a number of plugins that may be helpful to run simulation scenarios |
205+-----------------+---------------------------------------------------------------------+
206
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700207Logging
208-----------------
209
210Almost 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::
211
212 NS_LOG=CcnxFace:CcnxConsumer ./waf --run=ccnx-simple
213
214Refer 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 -0700215
216.. Indices and tables
217.. ==================
218
219.. * :ref:`genindex`
220.. * :ref:`modindex`
221.. * :ref:`search`
222