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 packet-level network simulator
   7 <http://www.nsnam.org>`_ as a SimGrid model, for example to investigate the
   8 validity of your simulation. Just install ns-3 and recompile SimGrid
   9 accordingly.
  10
  11 Compiling the ns-3/SimGrid binding
  12 **********************************
  13
  14 Installing ns-3
  15 ===============
  16
  17 SimGrid requires ns-3 version 3.26 or higher, and you probably want the most
  18 recent version of both SimGrid and ns-3. While the Debian package of SimGrid
  19 don't have the ns-3 bindings activated, you can still use the packaged version
  20 of ns-3 by grabbing the ``libns3-dev ns3`` packages. Alternatively, you can
  21 install ns-3 from scratch as follows:
  22
  23 .. code-block:: shell
  24
  25   # Download the source
  26   wget http://www.nsnam.org/release/ns-allinone-3.29.tar.bz2
  27   tar -xf ns-allinone-3.29.tar.bz2
  28   cd ns-allinone-3.29/ns-3.29/
  29   # Configure, build and install
  30   ./waf configure --prefix="/opt/ns3" # or give another path if you prefer
  31   ./waf
  32   ./waf install
  33
  34 For more information, please refer to the ns-3 documentation
  35 (`official website <http://www.nsnam.org>`_).
  36
  37 Enabling ns-3 in SimGrid
  38 ========================
  39
  40 SimGrid must be recompiled with the ``enable_ns3`` option activated in cmake.
  41 Optionally, use ``NS3_HINT`` to hint cmake about where to find ns-3.
  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. Otherwise, explore ``CMakeFiles/CMakeOutput.log`` and
  51 ``CMakeFiles/CMakeError.log`` to diagnose the problem.
  52
  53 Test your installation after compilation as follows:
  54
  55 .. code-block:: shell
  56
  57    ctest -R ns3
  58
  59 Troubleshooting
  60 ===============
  61
  62 If you use a version of ns-3 that is not known to SimGrid yet, edit
  63 ``tools/cmake/Modules/FindNS3.cmake`` in your SimGrid tree, according to the
  64 comments on top of this file. Conversely, if something goes wrong with an old
  65 version of either SimGrid or ns-3, try upgrading everything.
  66
  67 .. _ns3_use:
  68
  69 Using ns-3 from SimGrid
  70 ***********************
  71
  72 The SimGrid/ns-3 binding only contains features that are common to both
  73 systems: ns-3 wireless models are not available, while SimGrid routes
  74 cannot be longer than 1. Also, the platform built in ns-3 from the
  75 SimGrid description is very basic.
  76
  77 Platform files compatibility
  78 ============================
  79
  80 Any route longer than one will be ignored when using ns-3. They are
  81 harmless, but you still need to connect your hosts using one-hop routes.
  82 The best solution is to add routers to split your route. Here is an
  83 example of invalid platform:
  84
  85 .. code-block:: shell
  86
  87    <platform>
  88      <host id="alice" speed="1Gf" />
  89      <host id="bob"   speed="1Gf" />
  90
  91      <link id="l1" bw="1Mbps" />
  92      <link id="l2" bw="1Mbps" />
  93
  94      <route src="alice" dst="bob">
  95        <link_ctn id="l1"/>            <!-- !!!! INVALID WITH ns-3    !!!! -->
  96        <link_ctn id="l2"/>            <!-- !!!! length=2 IS TOO MUCH !!!! -->
  97      </route>
  98    </platform>
  99
 100 This can be reformulated as follows to make it usable with the ns-3 binding.
 101 There is no direct connection from alice to bob, but that's OK because
 102 ns-3 automatically routes from point to point.
 103
 104 .. code-block:: shell
 105
 106    <platform>
 107      <host id="alice" speed="1Gf" />
 108      <host id="bob"   speed="1Gf" />
 109
 110      <router id="r1" /> <!-- routers are compute-less hosts -->
 111
 112      <link id="l1" bw="1Mbps" />
 113      <link id="l2" bw="1Mbps" />
 114
 115      <route src="alice" dst="r1">
 116        <link_ctn id="l1"/>
 117      </route>
 118
 119      <route src="r1" dst="bob">
 120        <link_ctn id="l2"/>
 121      </route>
 122    </platform>
 123
 124 Once your platform is OK, just change the :ref:`network/model
 125 <options_model_select>` configuration option to "ns-3" as follows. The rest
 126 is unchanged.
 127
 128 .. code-block:: shell
 129
 130    ./network-ns3 --cfg=network/model:ns-3 (other parameters)
 131
 132 Many other files from the ``examples/platform directory`` are usable with the
 133 ns-3 model, such as `examples/platforms/dogbone.xml <https://framagit.org/simgrid/simgrid/tree/master/examples/platforms/dogbone.xml>`_.
 134 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>`_
 135 to see which ones are used in our regression tests.
 136
 137 Limitations
 138 ===========
 139
 140 A ns-3 platform is automatically created from the provided SimGrid
 141 platform. However, there are some known caveats:
 142
 143   * The default values (e.g., TCP parameters) are the ns-3 default values.
 144   * ns-3 networks are routed using the shortest path algorithm, using
 145     ``ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables``.
 146   * End hosts cannot have more than one interface card. So, your
 147     SimGrid hosts should be connected to the platform through only
 148     one link. Otherwise, your SimGrid host will be considered as a
 149     router.
 150
 151 Our goal is to keep the ns-3 plugin of SimGrid as easy (and hopefully readable)
 152 as possible. If the current state does not fit your needs, you should modify
 153 this plugin, and/or create your own plugin from the existing one. If you come up
 154 with interesting improvements, please contribute them back
 155
 156 Troubleshooting
 157 ===============
 158
 159 If your simulation hangs in a communication, this is probably because one host
 160 is sending data that is not routable in your platform. Make sure that you only
 161 use routes of length 1, and that any host is connected to the platform.
 162 Arguably, SimGrid could detect this situation and report it, but unfortunately,
 163 this is still to be done.