docs/source/ns3.rst

   1 .. _model_ns3:
   2
   3 ns-3 as a SimGrid model
   4 #######################
   5
   6 You can use the well-known `ns-3 <http://www.nsnam.org>`_ packet-level network
   7 simulator as a SimGrid model, for example to investigate the validity of your
   8 simulation. Just install ns-3 and recompile SimGrid accordingly.
   9
  10 Installing ns-3
  11 ***************
  12
  13 The easiest is to install it with the package manager. Under Debian/Ubuntu,
  14 simply type as root:
  15
  16 .. code-block:: shell
  17
  18   apt-get install libns3-dev ns3
  19
  20 You can also install it from scratch with the following commands:
  21
  22 .. code-block:: shell
  23
  24   # Download the source
  25   wget http://www.nsnam.org/release/ns-allinone-3.26.tar.bz2
  26   tar -xf ns-allinone-3.26.tar.bz2
  27   cd ns-allinone-3.26/ns-3.26/
  28   # Configure, build and install
  29   ./waf configure --prefix="/opt/ns3" # or give another path if you prefer
  30   ./waf
  31   ./waf install
  32
  33 For more information, please refer to the ns-3 documentation
  34 (`official website <http://www.nsnam.org>`_).
  35
  36 Enabling SimGrid's support for ns-3
  37 ***********************************
  38
  39 Normally, you just have to enable ns-3 in ccmake or cmake as
  40 follows. If you installed ns-3 in a regular path, just drop the
  41 NS3_HINT configuration item.
  42
  43 .. code-block:: shell
  44
  45    cmake . -Denable_ns3=ON -DNS3_HINT=/opt/ns3 # or change the path if needed
  46
  47 By the end of the configuration, cmake reports whether ns-3 was found,
  48 and this information is also available in ``include/simgrid/config.h``
  49 If your local copy defines the variable ``SIMGRID_HAVE_NS3`` to 1, then ns-3
  50 was correctly detected. If it's defined to 0, then something went
  51 wrong. Explore ``CMakeFiles/CMakeOutput.log`` and
  52 ``CMakeFiles/CMakeError.log`` to diagnose the problem.
  53
  54 Afterward, you can test your installation as follows:
  55
  56 .. code-block:: shell
  57
  58    ctest -R ns3
  59
  60 .. _ns3_use:
  61
  62 Using ns-3 from SimGrid
  63 ***********************
  64
  65 The SimGrid-ns3 binding only contains features that are common to both
  66 systems: ns-3 wireless models are not available, while SimGrid routes
  67 cannot be longer than 1. Also, the platform built in ns-3 from the
  68 SimGrid description is very basic.
  69
  70 Any route longer than one will be ignored when using ns-3. They are
  71 harmless, but you still need to connect your hosts using one-hop routes.
  72 The best solution is to add routers to split your route. Here is an
  73 example of invalid platform:
  74
  75 .. code-block:: shell
  76
  77    <platform>
  78      <host id="alice" speed="1Gf" />
  79      <host id="bob"   speed="1Gf" />
  80
  81      <link id="l1" bw="1Mbps" />
  82      <link id="l2" bw="1Mbps" />
  83
  84      <route src="alice" dst="bob">
  85        <link_ctn id="l1"/> <!-- INVALID WITH NS-3 -->
  86        <link_ctn id="l2"/> <!-- length=2 IS TOO MUCH -->
  87      </route>
  88    </platform>
  89
  90 Here is the same platform expressed in a way that ns-3 will understand.
  91 There is no direct connexion from alice to bob, but that's OK because
  92 ns-3 will find the path from point to point.
  93
  94 .. code-block:: shell
  95
  96    <platform>
  97      <host id="alice" speed="1Gf" />
  98      <host id="bob"   speed="1Gf" />
  99
 100      <router id="r1" /> <!-- routers are compute-less hosts -->
 101
 102      <link id="l1" bw="1Mbps" />
 103      <link id="l2" bw="1Mbps" />
 104
 105      <route src="alice" dst="r1">
 106        <link_ctn id="l1"/>
 107      </route>
 108
 109      <route src="r1" dst="bob">
 110        <link_ctn id="l2"/>
 111      </route>
 112    </platform>
 113
 114 Once your platform is OK, just change the :ref:`network/model
 115 <options_model_select>` configuration option to "NS3" as follows. The rest
 116 is unchanged.
 117
 118 .. code-block:: shell
 119
 120    ./network-ns3 --cfg=network/model:NS3 (other parameters)
 121
 122 Many other files from the ``examples/platform directory`` are usable with the
 123 ns-3 model, such as `examples/platforms/dogbone.xml <https://framagit.org/simgrid/simgrid/tree/master/examples/platforms/dogbone.xml>`_.
 124 Check the file  `examples/deprecated/msg/network-ns3/network-ns3.tesh <https://framagit.org/simgrid/simgrid/tree/master/examples/deprecated/msg/network-ns3/network-ns3.tesh>`_
 125 to see which ones are used in our regression tests.
 126
 127 Shortcomings of the ns-3 bindings in SimGrid
 128 --------------------------------------------
 129
 130 A ns-3 platform is automatically created from the provided SimGrid
 131 platform. However, there are some known caveats:
 132
 133   * The default values (e.g., TCP parameters) are the ns3 default values.
 134   * ns-3 networks are routed using the shortest path algorithm, using
 135     ``ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables``.
 136   * End hosts cannot have more than one interface card. So, your
 137     SimGrid hosts should be connected to the platform through only
 138     one link. Otherwise, your SimGrid host will be considered as a
 139     router.
 140
 141 Our goal is to keep the ns-3 plugin of SimGrid as easy (and hopefully
 142 readable) as possible. If the current state does not fit your needs,
 143 you should modify this plugin, and/or create your own plugin from the
 144 existing one.
 145
 146 Troubleshooting with ns-3 and SimGrid
 147 *************************************
 148
 149 I fail to compile ns-3 within SimGrid
 150 -------------------------------------
 151
 152 If you have a ns-3 version that is not known to SimGrid yet, edit
 153 ``tools/cmake/Modules/FindNS3.cmake`` in your SimGrid tree, according to
 154 the comments on top of this file.
 155
 156 If the compilation fails on Debian/Ubuntu when linking the library
 157 because of some .a file that cannot be used dynamically, then you are
 158 probably using a very old (and buggy) ``libns3-dev``
 159 package. Update it, or install ``libns3-3`` manually.
 160
 161 The simulation hangs at some point
 162 ----------------------------------
 163
 164 If your simulation hangs in a communication, this is probably because
 165 one host is sending data that is not routable in your platform. Make
 166 sure that you only use routes of length 1, and that any host is
 167 connected to the platform.
 168
 169 Arguably, SimGrid could detect this situation and report it, but
 170 unfortunately, this is still to be done.
 171
 172 I get a warning that some routes are ignored
 173 --------------------------------------------
 174
 175 Any routes longer than one hop are ignored in ns-3. Please refer to
 176 :ref:`ns3_use` for details.