Alexander Afanasyev | e095f0f | 2012-11-21 17:43:32 -0800 | [diff] [blame] | 1 | Getting Started |
| 2 | =============== |
| 3 | |
| 4 | Portability |
| 5 | ------------ |
| 6 | |
Alexander Afanasyev | 8e60bcd | 2015-01-15 20:55:40 +0000 | [diff] [blame] | 7 | ndnSIM 2.0 has been successfully compiled and used on following platforms: |
| 8 | |
| 9 | - Ubuntu Linux 12.04 (see the note) |
| 10 | - Ubuntu Linux 14.04 |
| 11 | - OS X 10.10 |
| 12 | |
| 13 | .. note:: |
| 14 | ndnSIM is currently cannot be compiled on Ubuntu Linux 12.04 with the packaged boost |
| 15 | libraries (there is an `issue with boost 1.48 and gcc 4.6 |
| 16 | <https://svn.boost.org/trac/boost/ticket/6153>`_). It is still possible to compile ndnSIM |
| 17 | on this platform, but either compiler or boost libraries (or both) need to get upgraded. |
| 18 | |
| 19 | More recent version of boost can be installed from "Boost C++ Libraries" team PPA:: |
| 20 | |
| 21 | sudo apt-get install python-software-properties |
| 22 | sudo add-apt-repository ppa:boost-latest/ppa |
| 23 | sudo apt-get update |
| 24 | sudo apt-get install libboost1.55-all-dev |
| 25 | |
Spyridon Mastorakis | f542c0b | 2015-08-11 22:59:18 -0700 | [diff] [blame] | 26 | # add --boost-libs=/usr/lib/x86_64-linux-gnu to ./waf configure |
Alexander Afanasyev | 8e60bcd | 2015-01-15 20:55:40 +0000 | [diff] [blame] | 27 | # ./waf configure --boost-libs=/usr/lib/x86_64-linux-gnu |
| 28 | |
| 29 | Make sure that all other version of boost libraries (``-dev`` packages) are removed, |
| 30 | otherwise compilation will fail. |
Alexander Afanasyev | e095f0f | 2012-11-21 17:43:32 -0800 | [diff] [blame] | 31 | |
| 32 | .. _requirements: |
| 33 | |
Spyridon Mastorakis | 460f57c | 2014-12-17 00:44:14 -0800 | [diff] [blame] | 34 | Prerequisites |
Alexander Afanasyev | e095f0f | 2012-11-21 17:43:32 -0800 | [diff] [blame] | 35 | ------------- |
| 36 | |
Spyridon Mastorakis | f542c0b | 2015-08-11 22:59:18 -0700 | [diff] [blame] | 37 | 1. `ndn-cxx library prerequisites <http://named-data.net/doc/ndn-cxx/current/INSTALL.html>`__. |
Alexander Afanasyev | e095f0f | 2012-11-21 17:43:32 -0800 | [diff] [blame] | 38 | |
Alexander Afanasyev | 26b558b | 2012-12-13 11:39:46 -0800 | [diff] [blame] | 39 | .. role:: red |
| 40 | |
Alexander Afanasyev | e095f0f | 2012-11-21 17:43:32 -0800 | [diff] [blame] | 41 | .. note:: |
Spyridon Mastorakis | c33e288 | 2015-01-20 21:45:44 -0800 | [diff] [blame] | 42 | :red:`ndnSIM requires boost version at least 1.49.` Many linux distribution |
Spyridon Mastorakis | 460f57c | 2014-12-17 00:44:14 -0800 | [diff] [blame] | 43 | (Fedora 16, 17 at the time of this writing) ship an old version of boost, making it |
| 44 | impossible to compile ndnSIM out-of-the-box. Please install the latest version, following |
| 45 | :ref:`these simple instructions <Installing boost libraries>`. |
Alexander Afanasyev | 9ab7d67 | 2013-08-11 11:02:52 -0700 | [diff] [blame] | 46 | |
| 47 | .. note:: |
Spyridon Mastorakis | c33e288 | 2015-01-20 21:45:44 -0800 | [diff] [blame] | 48 | If you do not have root permissions to install boost, you can install it in your home |
Spyridon Mastorakis | 460f57c | 2014-12-17 00:44:14 -0800 | [diff] [blame] | 49 | folder. However, you need to be make sure that `libboost_iostreams` library is successfully |
| 50 | compiled and is installed. Please refer to :ref:`the following example <Installing boost |
| 51 | libraries>` for the hints how to successfully compile and install boost libraries on Ubuntu |
| 52 | Linux. |
Alexander Afanasyev | e095f0f | 2012-11-21 17:43:32 -0800 | [diff] [blame] | 53 | |
| 54 | |
Spyridon Mastorakis | 460f57c | 2014-12-17 00:44:14 -0800 | [diff] [blame] | 55 | 2. If you are planning to use other modules, like visualizer, a number of additional |
| 56 | dependencies should be installed. For example, in order to run `visualizer`_ module, the |
| 57 | following should be installed: |
Alexander Afanasyev | e095f0f | 2012-11-21 17:43:32 -0800 | [diff] [blame] | 58 | |
Alexander Afanasyev | 8e60bcd | 2015-01-15 20:55:40 +0000 | [diff] [blame] | 59 | * For Ubuntu: |
Alexander Afanasyev | e095f0f | 2012-11-21 17:43:32 -0800 | [diff] [blame] | 60 | |
Alexander Afanasyev | 326410e | 2013-03-09 20:39:11 -0800 | [diff] [blame] | 61 | .. code-block:: bash |
Alexander Afanasyev | e095f0f | 2012-11-21 17:43:32 -0800 | [diff] [blame] | 62 | |
Alexander Afanasyev | 326410e | 2013-03-09 20:39:11 -0800 | [diff] [blame] | 63 | sudo apt-get install python-dev python-pygraphviz python-kiwi |
| 64 | sudo apt-get install python-pygoocanvas python-gnome2 |
Alexander Afanasyev | df26b5a | 2015-01-15 23:30:56 -0800 | [diff] [blame] | 65 | sudo apt-get install python-rsvg ipython |
Alexander Afanasyev | e095f0f | 2012-11-21 17:43:32 -0800 | [diff] [blame] | 66 | |
Alexander Afanasyev | 8e60bcd | 2015-01-15 20:55:40 +0000 | [diff] [blame] | 67 | * For Fedora: |
Alexander Afanasyev | e095f0f | 2012-11-21 17:43:32 -0800 | [diff] [blame] | 68 | |
Alexander Afanasyev | 326410e | 2013-03-09 20:39:11 -0800 | [diff] [blame] | 69 | .. code-block:: bash |
| 70 | |
| 71 | sudo yum install pygoocanvas python-kiwi graphviz-python |
| 72 | |
Alexander Afanasyev | 9ab7d67 | 2013-08-11 11:02:52 -0700 | [diff] [blame] | 73 | # easy_install method, since pygraphviz is not (yet?) packaged into Fedora (https://bugzilla.redhat.com/show_bug.cgi?id=740687) |
Alexander Afanasyev | 326410e | 2013-03-09 20:39:11 -0800 | [diff] [blame] | 74 | sudo yum install graphviz-devel |
| 75 | sudo yum install python-pip |
| 76 | sudo easy_install pygraphviz |
| 77 | |
Alexander Afanasyev | 8e60bcd | 2015-01-15 20:55:40 +0000 | [diff] [blame] | 78 | * For OS X with MacPorts: |
Alexander Afanasyev | 326410e | 2013-03-09 20:39:11 -0800 | [diff] [blame] | 79 | |
| 80 | .. code-block:: bash |
| 81 | |
| 82 | sudo port install py27-pygraphviz py27-goocanvas |
| 83 | |
Spyridon Mastorakis | 460f57c | 2014-12-17 00:44:14 -0800 | [diff] [blame] | 84 | # If you add NDN macports repository, as described in |
| 85 | # http://named-data.net/doc/NFD/current/INSTALL.html#install-nfd-using-the-ndn-macports-repository-on-os-x |
| 86 | # you will be able to install another useful python module |
| 87 | # sudo port install py27-kiwi |
Alexander Afanasyev | e095f0f | 2012-11-21 17:43:32 -0800 | [diff] [blame] | 88 | |
Alexander Afanasyev | df26b5a | 2015-01-15 23:30:56 -0800 | [diff] [blame] | 89 | * For OS X with HomeBrew |
| 90 | |
| 91 | .. code-block:: bash |
| 92 | |
| 93 | brew install boost cryptopp pkg-config libxml2 |
| 94 | brew link --force libxml2 |
| 95 | |
Alexander Afanasyev | e095f0f | 2012-11-21 17:43:32 -0800 | [diff] [blame] | 96 | .. _visualizer: http://www.nsnam.org/wiki/index.php/PyViz |
| 97 | |
| 98 | Downloading ndnSIM source |
| 99 | ------------------------- |
| 100 | |
Spyridon Mastorakis | 460f57c | 2014-12-17 00:44:14 -0800 | [diff] [blame] | 101 | ndnSIM package consists of three pieces: |
| 102 | |
Spyridon Mastorakis | 460f57c | 2014-12-17 00:44:14 -0800 | [diff] [blame] | 103 | - a custom branch of NS-3 that contains a few useful patches |
| 104 | - a customized python binding generation library (necessary if you want to use NS-3's python |
| 105 | bindings and/or visualizer module) |
| 106 | - the source code of ndnSIM module |
| 107 | |
| 108 | The following commands download all pieces from GitHub repositories: |
Alexander Afanasyev | 326410e | 2013-03-09 20:39:11 -0800 | [diff] [blame] | 109 | |
| 110 | .. code-block:: bash |
Alexander Afanasyev | e095f0f | 2012-11-21 17:43:32 -0800 | [diff] [blame] | 111 | |
Spyridon Mastorakis | 460f57c | 2014-12-17 00:44:14 -0800 | [diff] [blame] | 112 | mkdir ndnSIM |
| 113 | cd ndnSIM |
Alexander Afanasyev | d6453cd | 2015-08-20 21:45:36 -0700 | [diff] [blame] | 114 | git clone https://github.com/named-data-ndnSIM/ns-3-dev.git ns-3 |
| 115 | git clone https://github.com/named-data-ndnSIM/pybindgen.git pybindgen |
Spyridon Mastorakis | a1d135b | 2015-08-20 20:24:59 -0700 | [diff] [blame] | 116 | git clone --recursive https://github.com/named-data-ndnSIM/ndnSIM.git ns-3/src/ndnSIM |
Alexander Afanasyev | e095f0f | 2012-11-21 17:43:32 -0800 | [diff] [blame] | 117 | |
Spyridon Mastorakis | 460f57c | 2014-12-17 00:44:14 -0800 | [diff] [blame] | 118 | The few modification to the base NS-3 code are necessary to run ndnSIM, and the code is |
| 119 | periodically synchronized with the official developer branch. Eventually, all the changes will |
| 120 | be merged to the official branch, but for the time being, it is necessary to use the customized |
| 121 | branch. |
Alexander Afanasyev | e095f0f | 2012-11-21 17:43:32 -0800 | [diff] [blame] | 122 | |
Alexander Afanasyev | 701e508 | 2013-03-13 09:47:50 -0700 | [diff] [blame] | 123 | |
Alexander Afanasyev | e095f0f | 2012-11-21 17:43:32 -0800 | [diff] [blame] | 124 | Compiling and running ndnSIM |
| 125 | ---------------------------- |
| 126 | |
Spyridon Mastorakis | 460f57c | 2014-12-17 00:44:14 -0800 | [diff] [blame] | 127 | - Compile NS-3 with ndnSIM module |
Alexander Afanasyev | 326410e | 2013-03-09 20:39:11 -0800 | [diff] [blame] | 128 | |
Spyridon Mastorakis | 460f57c | 2014-12-17 00:44:14 -0800 | [diff] [blame] | 129 | ndnSIM uses standard NS-3 compilation procedure. Normally the following commands should be |
| 130 | sufficient to configure and build ndnSIM with python bindings enabled: |
Alexander Afanasyev | e095f0f | 2012-11-21 17:43:32 -0800 | [diff] [blame] | 131 | |
Spyridon Mastorakis | 460f57c | 2014-12-17 00:44:14 -0800 | [diff] [blame] | 132 | .. code-block:: bash |
Alexander Afanasyev | e095f0f | 2012-11-21 17:43:32 -0800 | [diff] [blame] | 133 | |
Spyridon Mastorakis | 460f57c | 2014-12-17 00:44:14 -0800 | [diff] [blame] | 134 | cd <ns-3-folder> |
| 135 | ./waf configure --enable-examples |
| 136 | ./waf |
Alexander Afanasyev | e095f0f | 2012-11-21 17:43:32 -0800 | [diff] [blame] | 137 | |
Spyridon Mastorakis | 460f57c | 2014-12-17 00:44:14 -0800 | [diff] [blame] | 138 | On MacOS (with macports), you may need to modify the configure command to use macports |
| 139 | version of python: |
Alexander Afanasyev | 326410e | 2013-03-09 20:39:11 -0800 | [diff] [blame] | 140 | |
Spyridon Mastorakis | 460f57c | 2014-12-17 00:44:14 -0800 | [diff] [blame] | 141 | .. code-block:: bash |
Alexander Afanasyev | e095f0f | 2012-11-21 17:43:32 -0800 | [diff] [blame] | 142 | |
Spyridon Mastorakis | 460f57c | 2014-12-17 00:44:14 -0800 | [diff] [blame] | 143 | cd <ns-3-folder> |
| 144 | ./waf configure --with-python=/opt/local/bin/python2.7 --enable-examples |
| 145 | # or run ``sudo port select python python27`` |
| 146 | ./waf |
Alexander Afanasyev | e095f0f | 2012-11-21 17:43:32 -0800 | [diff] [blame] | 147 | |
Spyridon Mastorakis | c33e288 | 2015-01-20 21:45:44 -0800 | [diff] [blame] | 148 | .. note:: |
| 149 | On OS X configuration stage may get :ref:`stuck at detecting gtk module <Problems with |
| 150 | the gtk python module on OS X>`. Make sure you have `XQuartz |
| 151 | <http://xquartz.macosforge.org>`_ installed or disable python as described in the |
| 152 | following instructions. |
| 153 | |
Spyridon Mastorakis | 460f57c | 2014-12-17 00:44:14 -0800 | [diff] [blame] | 154 | Python bindings is an optional and not very stable feature of NS-3 simulator. It is |
| 155 | possible to disable python bindings compilation either to speed up compilation or to avoid |
| 156 | certain compilation errors (e.g., "Could not find a task generator for the name |
| 157 | 'ns3-visualizer'"): |
Alexander Afanasyev | 326410e | 2013-03-09 20:39:11 -0800 | [diff] [blame] | 158 | |
Spyridon Mastorakis | 460f57c | 2014-12-17 00:44:14 -0800 | [diff] [blame] | 159 | .. code-block:: bash |
Alexander Afanasyev | e095f0f | 2012-11-21 17:43:32 -0800 | [diff] [blame] | 160 | |
Spyridon Mastorakis | 460f57c | 2014-12-17 00:44:14 -0800 | [diff] [blame] | 161 | cd <ns-3-folder> |
| 162 | ./waf configure --disable-python --enable-examples |
| 163 | ./waf |
Alexander Afanasyev | e095f0f | 2012-11-21 17:43:32 -0800 | [diff] [blame] | 164 | |
Spyridon Mastorakis | 460f57c | 2014-12-17 00:44:14 -0800 | [diff] [blame] | 165 | For more configuration options, please refer to ``./waf --help``. |
Alexander Afanasyev | e095f0f | 2012-11-21 17:43:32 -0800 | [diff] [blame] | 166 | |
Spyridon Mastorakis | f34b319 | 2015-02-16 17:42:01 -0800 | [diff] [blame] | 167 | |
Alexander Afanasyev | 701e508 | 2013-03-13 09:47:50 -0700 | [diff] [blame] | 168 | Simulating using ndnSIM |
| 169 | ----------------------- |
| 170 | |
Spyridon Mastorakis | 460f57c | 2014-12-17 00:44:14 -0800 | [diff] [blame] | 171 | - Examples simulations |
Alexander Afanasyev | 701e508 | 2013-03-13 09:47:50 -0700 | [diff] [blame] | 172 | |
Spyridon Mastorakis | 460f57c | 2014-12-17 00:44:14 -0800 | [diff] [blame] | 173 | When NS-3 is compiled with ``--with-examples`` flag, you can directly run all examples |
| 174 | described in :doc:`examples section of this tutorial <examples>`. For example, to run |
| 175 | ``ndn-simple.cpp`` scenario, you can run the following command: |
Alexander Afanasyev | 701e508 | 2013-03-13 09:47:50 -0700 | [diff] [blame] | 176 | |
Spyridon Mastorakis | 460f57c | 2014-12-17 00:44:14 -0800 | [diff] [blame] | 177 | .. code-block:: bash |
Alexander Afanasyev | 701e508 | 2013-03-13 09:47:50 -0700 | [diff] [blame] | 178 | |
Spyridon Mastorakis | 460f57c | 2014-12-17 00:44:14 -0800 | [diff] [blame] | 179 | ./waf --run=ndn-simple |
| 180 | |
Spyridon Mastorakis | c33e288 | 2015-01-20 21:45:44 -0800 | [diff] [blame] | 181 | To run ``ndn-grid.cpp`` scenario: |
Spyridon Mastorakis | 460f57c | 2014-12-17 00:44:14 -0800 | [diff] [blame] | 182 | |
| 183 | .. code-block:: bash |
| 184 | |
| 185 | ./waf --run=ndn-grid |
| 186 | |
| 187 | To run the sample simulation scenarios with the logging module of NS-3 enabled (note that |
| 188 | this will work only when NS-3 is compiled in debug mode): |
| 189 | |
| 190 | .. code-block:: bash |
| 191 | |
| 192 | NS_LOG=ndn.Producer:ndn.Consumer ./waf --run=<scenario name> |
| 193 | |
| 194 | If you have compiled with python bindings, then you can try to run these simulations with |
| 195 | visualizer: |
| 196 | |
| 197 | .. code-block:: bash |
| 198 | |
| 199 | ./waf --run=ndn-simple --vis |
| 200 | |
| 201 | or: |
| 202 | |
| 203 | .. code-block:: bash |
| 204 | |
| 205 | ./waf --run=ndn-grid --vis |
| 206 | |
| 207 | .. note:: |
| 208 | Do not forget to configure and compile NS-3 in optimized mode (``./waf configure -d |
| 209 | optimized``) in order to run actual simulations. |
| 210 | |
| 211 | - Real experimentation |
| 212 | |
| 213 | While it is possible to write simulations directly inside NS-3 (in ``scratch/`` folder) or |
| 214 | ndnSIM (in ``examples/``), the recommended way is to write your simulation scenarios, as |
| 215 | well as any custom extensions, separately from the NS-3 or ndnSIM core. |
| 216 | |
| 217 | For example, you can use the following template to write your extensions, simulation |
| 218 | scenarios, and metric processing scripts: |
| 219 | `<http://github.com/cawka/ndnSIM-scenario-template>`_: |
| 220 | |
| 221 | .. code-block:: bash |
| 222 | |
| 223 | mkdir ndnSIM |
| 224 | cd ndnSIM |
Alexander Afanasyev | d6453cd | 2015-08-20 21:45:36 -0700 | [diff] [blame] | 225 | git clone https://github.com/named-data-ndnSIM/ns-3-dev.git ns-3 |
| 226 | git clone https://github.com/named-data-ndnSIM/pybindgen.git pybindgen |
Spyridon Mastorakis | a1d135b | 2015-08-20 20:24:59 -0700 | [diff] [blame] | 227 | git clone --recursive https://github.com/named-data-ndnSIM/ndnSIM.git ns-3/src/ndnSIM |
Alexander Afanasyev | 701e508 | 2013-03-13 09:47:50 -0700 | [diff] [blame] | 228 | |
| 229 | # Build and install NS-3 and ndnSIM |
| 230 | cd ns-3 |
| 231 | ./waf configure -d optimized |
| 232 | ./waf |
| 233 | |
| 234 | sudo ./waf install |
| 235 | cd .. |
| 236 | |
Alexander Afanasyev | d6453cd | 2015-08-20 21:45:36 -0700 | [diff] [blame] | 237 | git clone https://github.com/named-data-ndnSIM/scenario-template.git scenario |
Alexander Afanasyev | 701e508 | 2013-03-13 09:47:50 -0700 | [diff] [blame] | 238 | cd scenario |
Alexander Afanasyev | 9ab7d67 | 2013-08-11 11:02:52 -0700 | [diff] [blame] | 239 | export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig |
Alexander Afanasyev | 701e508 | 2013-03-13 09:47:50 -0700 | [diff] [blame] | 240 | export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH |
| 241 | |
| 242 | ./waf configure |
| 243 | |
| 244 | ./waf --run <scenario> |
| 245 | |
Spyridon Mastorakis | 460f57c | 2014-12-17 00:44:14 -0800 | [diff] [blame] | 246 | For more detailed information, refer to `README file |
| 247 | <https://github.com/cawka/ndnSIM-scenario-template/blob/master/README.md>`_. |
Alexander Afanasyev | 701e508 | 2013-03-13 09:47:50 -0700 | [diff] [blame] | 248 | |
| 249 | Examples of template-based simulations |
| 250 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 251 | |
Alexander Afanasyev | 9ab7d67 | 2013-08-11 11:02:52 -0700 | [diff] [blame] | 252 | 1. ndnSIM examples from `<http://ndnsim.net>`_ website and more: |
Alexander Afanasyev | 701e508 | 2013-03-13 09:47:50 -0700 | [diff] [blame] | 253 | |
| 254 | - `<http://github.com/cawka/ndnSIM-examples>`_, or |
Alexander Afanasyev | 701e508 | 2013-03-13 09:47:50 -0700 | [diff] [blame] | 255 | |
Spyridon Mastorakis | 460f57c | 2014-12-17 00:44:14 -0800 | [diff] [blame] | 256 | 2. Script scenarios and graph processing scripts for simulations used in "A Case for Stateful |
| 257 | Forwarding Plane" paper by Yi et al. (`<http://dx.doi.org/10.1016/j.comcom.2013.01.005>`_): |
Alexander Afanasyev | 701e508 | 2013-03-13 09:47:50 -0700 | [diff] [blame] | 258 | |
| 259 | - `<http://github.com/cawka/ndnSIM-comcom-stateful-fw>`_, or |
Alexander Afanasyev | 701e508 | 2013-03-13 09:47:50 -0700 | [diff] [blame] | 260 | |
Spyridon Mastorakis | 460f57c | 2014-12-17 00:44:14 -0800 | [diff] [blame] | 261 | 3. Script scenarios and graph processing scripts for simulations used in "Rapid Traffic |
| 262 | Information Dissemination Using Named Data" paper by Wang et |
| 263 | al. (`<http://dx.doi.org/10.1145/2248361.2248365>`_): |
Alexander Afanasyev | 701e508 | 2013-03-13 09:47:50 -0700 | [diff] [blame] | 264 | |
| 265 | - `<http://github.com/cawka/ndnSIM-nom-rapid-car2car>`_, or |
Alexander Afanasyev | 701e508 | 2013-03-13 09:47:50 -0700 | [diff] [blame] | 266 | |
Spyridon Mastorakis | 460f57c | 2014-12-17 00:44:14 -0800 | [diff] [blame] | 267 | - Rocketfuel-based topology generator for ndnSIM preferred format (randomly assigned link |
| 268 | delays and bandwidth, based on estimated types of connections between nodes): |
Alexander Afanasyev | 701e508 | 2013-03-13 09:47:50 -0700 | [diff] [blame] | 269 | |
| 270 | - `<http://github.com/cawka/ndnSIM-sample-topologies>`_, or |