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 (see the `ns-3 documentation <http://www.nsnam.org>`_).
  22
  23 Enabling ns-3 in SimGrid
  24 ========================
  25
  26 SimGrid must be recompiled with the ``enable_ns3`` option activated in cmake.
  27 Optionally, use ``NS3_HINT`` to tell cmake where ns3 is installed on
  28 your disk.
  29
  30 .. code-block:: shell
  31
  32    cmake . -Denable_ns3=ON -DNS3_HINT=/opt/ns3 # or change the path if needed
  33
  34 By the end of the configuration, cmake reports whether ns-3 was found,
  35 and this information is also available in ``include/simgrid/config.h``
  36 If your local copy defines the variable ``SIMGRID_HAVE_NS3`` to 1, then ns-3
  37 was correctly detected. Otherwise, explore ``CMakeFiles/CMakeOutput.log`` and
  38 ``CMakeFiles/CMakeError.log`` to diagnose the problem.
  39
  40 Test your installation after compilation as follows:
  41
  42 .. code-block:: shell
  43
  44    ctest -R ns3
  45
  46 Troubleshooting
  47 ===============
  48
  49 If you use a version of ns-3 that is not known to SimGrid yet, edit
  50 ``tools/cmake/Modules/FindNS3.cmake`` in your SimGrid tree, according to the
  51 comments on top of this file. Conversely, if something goes wrong with an old
  52 version of either SimGrid or ns-3, try upgrading everything.
  53
  54 .. _ns3_use:
  55
  56 Using ns-3 from SimGrid
  57 ***********************
  58
  59 The SimGrid/ns-3 binding only contains features that are common to both
  60 systems: ns-3 wireless models are not available, while SimGrid routes
  61 cannot be longer than 1. Also, the platform built in ns-3 from the
  62 SimGrid description is very basic.
  63
  64 Platform files compatibility
  65 ============================
  66
  67 Any route longer than one will be ignored when using ns-3. They are
  68 harmless, but you still need to connect your hosts using one-hop routes.
  69 The best solution is to add routers to split your route. Here is an
  70 example of an invalid platform:
  71
  72 .. code-block:: shell
  73
  74    <platform>
  75      <zone id="zone0" routing="Full">
  76        <host id="alice" speed="1Gf" />
  77        <host id="bob"   speed="1Gf" />
  78
  79        <link id="l1" bw="1Mbps" />
  80        <link id="l2" bw="1Mbps" />
  81
  82        <route src="alice" dst="bob">
  83          <link_ctn id="l1"/>            <!-- !!!! INVALID WITH ns-3    !!!! -->
  84          <link_ctn id="l2"/>            <!-- !!!! length=2 IS TOO MUCH !!!! -->
  85        </route>
  86      </zone>
  87    </platform>
  88
  89 This can be reformulated as follows to make it usable with the ns-3 binding.
  90 There is no direct connection from alice to bob, but that's OK because
  91 ns-3 automatically routes from point to point.
  92
  93 .. code-block:: shell
  94
  95    <platform>
  96      <zone id="zone0" routing="Full">
  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      </zone>
 113    </platform>
 114
 115 Once your platform is OK, just change the :ref:`network/model
 116 <options_model_select>` configuration option to "ns-3" as follows. The rest
 117 is unchanged.
 118
 119 .. code-block:: shell
 120
 121    ./network-ns3 --cfg=network/model:ns-3 (other parameters)
 122
 123 Many other files from the ``examples/platform directory`` are usable with the
 124 ns-3 model, such as `examples/platforms/dogbone.xml <https://framagit.org/simgrid/simgrid/tree/master/examples/platforms/dogbone.xml>`_.
 125 Check the file  `examples/s4u/network-ns3/network-ns3.tesh <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/network-ns3/network-ns3.tesh>`_
 126 to see which ones are used in our regression tests.
 127
 128 Limitations
 129 ===========
 130
 131 A ns-3 platform is automatically created from the provided SimGrid
 132 platform. However, there are some known caveats:
 133
 134   * The default values (e.g., TCP parameters) are the ns-3 default values.
 135   * ns-3 networks are routed using the shortest path algorithm, using
 136     ``ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables``.
 137   * End hosts cannot have more than one interface card. So, your
 138     SimGrid hosts should be connected to the platform through only
 139     one link. Otherwise, your SimGrid host will be considered as a
 140     router.
 141
 142 Our goal is to keep the ns-3 plugin of SimGrid as easy (and hopefully readable)
 143 as possible. If the current state does not fit your needs, you should modify
 144 this plugin, and/or create your own plugin from the existing one. If you come up
 145 with interesting improvements, please contribute them back.
 146
 147 Troubleshooting
 148 ===============
 149
 150 If your simulation hangs in a communication, this is probably because one host
 151 is sending data that is not routable in your platform. Make sure that you only
 152 use routes of length 1, and that any host is connected to the platform.
 153 Arguably, SimGrid could detect this situation and report it, but unfortunately,
 154 this is still to be done.