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 The SimGrid/ns-3 binding only contains features that are common to both systems.
  12 Not all ns-3 models are available from SimGrid (only the TCP and WiFi ones are),
  13 while not all SimGrid platform files can be used in conjunction ns-3 (routes
  14 must be of length 1). Also, the platform built in ns-3 from the SimGrid
  15 description is very basic.
  16
  17
  18 Compiling the ns-3/SimGrid binding
  19 **********************************
  20
  21 Installing ns-3
  22 ===============
  23
  24 SimGrid requires ns-3 version 3.26 or higher, and you probably want the most
  25 recent version of both SimGrid and ns-3. While the Debian package of SimGrid
  26 don't have the ns-3 bindings activated, you can still use the packaged version
  27 of ns-3 by grabbing the ``libns3-dev ns3`` packages. Alternatively, you can
  28 install ns-3 from scratch (see the `ns-3 documentation <http://www.nsnam.org>`_).
  29
  30 Enabling ns-3 in SimGrid
  31 ========================
  32
  33 SimGrid must be recompiled with the ``enable_ns3`` option activated in cmake.
  34 Optionally, use ``NS3_HINT`` to tell cmake where ns3 is installed on
  35 your disk.
  36
  37 .. code-block:: shell
  38
  39    cmake . -Denable_ns3=ON -DNS3_HINT=/opt/ns3 # or change the path if needed
  40
  41 By the end of the configuration, cmake reports whether ns-3 was found,
  42 and this information is also available in ``include/simgrid/config.h``
  43 If your local copy defines the variable ``SIMGRID_HAVE_NS3`` to 1, then ns-3
  44 was correctly detected. Otherwise, explore ``CMakeFiles/CMakeOutput.log`` and
  45 ``CMakeFiles/CMakeError.log`` to diagnose the problem.
  46
  47 Test that ns-3 was successfully integrated with the following (from your SimGrid
  48 build directory). It will run all SimGrid tests that are related to the ns-3
  49 integration. If no test is run at all, you probably forgot to enable ns-3 in cmake.
  50
  51 .. code-block:: shell
  52
  53    ctest -R ns3
  54
  55 Troubleshooting
  56 ===============
  57
  58 If you use a version of ns-3 that is not known to SimGrid yet, edit
  59 ``tools/cmake/Modules/FindNS3.cmake`` in your SimGrid tree, according to the
  60 comments on top of this file. Conversely, if something goes wrong with an old
  61 version of either SimGrid or ns-3, try upgrading everything.
  62
  63 .. _ns3_use:
  64
  65 Using ns-3 from SimGrid
  66 ***********************
  67
  68 Platform files compatibility
  69 ============================
  70
  71 Any route longer than one will be ignored when using ns-3. They are
  72 harmless, but you still need to connect your hosts using one-hop routes.
  73 The best solution is to add routers to split your route. Here is an
  74 example of an invalid platform:
  75
  76 .. code-block:: xml
  77
  78    <?xml version='1.0'?>
  79    <!DOCTYPE platform SYSTEM "https://simgrid.org/simgrid.dtd">
  80    <platform version="4.1">
  81      <zone id="zone0" routing="Floyd">
  82        <host id="alice" speed="1Gf" />
  83        <host id="bob"   speed="1Gf" />
  84
  85        <link id="l1" bandwidth="1Mbps" latency="5ms" />
  86        <link id="l2" bandwidth="1Mbps" latency="5ms" />
  87
  88        <route src="alice" dst="bob">
  89          <link_ctn id="l1"/>            <!-- !!!! IGNORED WHEN USED WITH ns-3       !!!! -->
  90          <link_ctn id="l2"/>            <!-- !!!! ROUTES MUST CONTAIN ONE LINK ONLY !!!! -->
  91        </route>
  92      </zone>
  93    </platform>
  94
  95 This can be reformulated as follows to make it usable with the ns-3 binding.
  96 There is no direct connection from alice to bob, but that's OK because ns-3
  97 automatically routes from point to point (using
  98 ``ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables``).
  99
 100 .. code-block:: xml
 101
 102    <?xml version='1.0'?>
 103    <!DOCTYPE platform SYSTEM "https://simgrid.org/simgrid.dtd">
 104    <platform version="4.1">
 105      <zone id="zone0" routing="Full">
 106        <host id="alice" speed="1Gf" />
 107        <host id="bob"   speed="1Gf" />
 108
 109        <router id="r1" /> <!-- routers are compute-less hosts -->
 110
 111        <link id="l1" bandwidth="1Mbps" latency="5ms"/>
 112        <link id="l2" bandwidth="1Mbps" latency="5ms"/>
 113
 114        <route src="alice" dst="r1">
 115          <link_ctn id="l1"/>
 116        </route>
 117
 118        <route src="r1" dst="bob">
 119          <link_ctn id="l2"/>
 120        </route>
 121      </zone>
 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 other
 126 options can be used as usual.
 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/s4u/network-ns3/network-ns3.tesh <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/network-ns3/network-ns3.tesh>`_
 135 to see which ones are used in our regression tests.
 136
 137 WiFi platforms
 138 --------------
 139
 140 In SimGrid, WiFi networks are modeled as regular links with a specific
 141 attribute, and these links are then added to routes between hosts. The main
 142 difference When using ns-3 WiFi networks is that the network performance is not
 143 given by the link bandwidth and latency but by the access point WiFi
 144 characteristics, and the distance between the access point and the hosts (called
 145 station in the WiFi world).
 146
 147 So, to declare a new WiFi network, simply declare a link with the ``WiFi``
 148 sharing policy as you would do in a pure SimGrid simulation (you must still
 149 provide the ``bandwidth`` and ``latency`` attributes even if they are ignored,
 150 because they are mandatory to the SimGrid XML parser).
 151
 152 .. code-block:: xml
 153
 154          <link id="net0" bandwidth="0" latency="0" sharing_policy="WIFI"/>
 155
 156 To declare that a given host is connected to this WiFi zone, use the
 157 ``wifi_link`` property of that host. The property value must be the link id that
 158 you want to use as a WiFi zone. This is not needed when using pure SimGrid wifi,
 159 only when using ns-3 wifi, because the wifi performance is :ref:`configured <ns3_wifi_perf>`.
 160
 161 .. code-block:: xml
 162
 163    <host id="alice" speed="1Gf">
 164      <prop id="wifi_link" value="net0"/>
 165    </host>
 166
 167 To connect the station node to the access point node, simply create a route
 168 between them:
 169
 170 .. code-block:: xml
 171
 172    <route src="alice" dst="bob">
 173      <link_ctn id="net0" />
 174    </route>
 175
 176 .. _ns3_wifi_perf:
 177
 178 WiFi network performance
 179 ^^^^^^^^^^^^^^^^^^^^^^^^
 180
 181
 182 The performance of a wifi network is controlled by 3 property that can be added
 183 to the an host connected to the wifi zone:
 184
 185  * ``wifi_mcs`` (`Modulation and Coding Scheme <https://en.wikipedia.org/wiki/Link_adaptation>`_)
 186    Roughly speaking, it defines the speed at which the access point is
 187    exchanging data with all stations. It depends on its model and configuration,
 188    and the possible values are listed for example on Wikipedia.
 189    |br| By default, ``wifi_mcs=3``.
 190  * ``wifi_nss`` (Number of Spatial Streams, or `number of antennas <https://en.wikipedia.org/wiki/IEEE_802.11n-2009#Number_of_antennas>`_)
 191    defines the amount of simultaneous data streams that the AP can sustain.
 192    Not all value of MCS and NSS are valid nor compatible (cf. `802.11n standard <https://en.wikipedia.org/wiki/IEEE_802.11n-2009#Data_rates>`_).
 193    |br| By default, ``wifi_nss=1``.
 194  * ``wifi_distance`` is the distance from the station to the access point. Each
 195    station can have a specific value.
 196    |br| By default, ``wifi_distance=10``.
 197
 198 Here is an example of host changing all these values:
 199
 200 .. code-block:: xml
 201
 202    <host id="alice" speed="100.0Mf,50.0Mf,20.0Mf" pstate="0">
 203      <prop id="wifi_link" value="net0"/>
 204      <prop id="wifi_mcs" value="5"/>
 205      <prop id="wifi_nss" value="2"/>
 206      <prop id="wifi_distance" value="30" />
 207    </host>
 208
 209 Limitations
 210 ===========
 211
 212 A ns-3 platform is automatically created from the provided SimGrid
 213 platform. However, there are some known caveats:
 214
 215   * The default values (e.g., TCP parameters) are the ns-3 default values.
 216   * ns-3 networks are routed using the shortest path algorithm, using ``ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables``.
 217   * End hosts cannot have more than one interface card. So, your SimGrid hosts
 218     should be connected to the platform through only one link. Otherwise, your
 219     SimGrid host will be considered as a router (FIXME: is it still true?).
 220
 221 Our goal is to keep the ns-3 plugin of SimGrid as easy (and hopefully readable)
 222 as possible. If the current state does not fit your needs, you should modify
 223 this plugin, and/or create your own plugin from the existing one. If you come up
 224 with interesting improvements, please contribute them back.
 225
 226 Troubleshooting
 227 ===============
 228
 229 If your simulation hangs in a communication, this is probably because one host
 230 is sending data that is not routable in your platform. Make sure that you only
 231 use routes of length 1, and that any host is connected to the platform.
 232 Arguably, SimGrid could detect this situation and report it, but unfortunately,
 233 this is still to be done.
 234
 235 .. |br| raw:: html
 236
 237    <br />