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. Finally, communicating from a host to
  16 itself is forbidden in ns-3, so every such communication completes
  17 immediately upon startup.
  18
  19
  20 Compiling the ns-3/SimGrid binding
  21 **********************************
  22
  23 Installing ns-3
  24 ===============
  25
  26 SimGrid requires ns-3 version 3.26 or higher, and you probably want the most
  27 recent version of both SimGrid and ns-3. While the Debian package of SimGrid
  28 don't have the ns-3 bindings activated, you can still use the packaged version
  29 of ns-3 by grabbing the ``libns3-dev ns3`` packages. Alternatively, you can
  30 install ns-3 from scratch (see the `ns-3 documentation <http://www.nsnam.org>`_).
  31
  32 Enabling ns-3 in SimGrid
  33 ========================
  34
  35 SimGrid must be recompiled with the ``enable_ns3`` option activated in cmake.
  36 Optionally, use ``NS3_HINT`` to tell cmake where ns3 is installed on
  37 your disk.
  38
  39 .. code-block:: shell
  40
  41    cmake . -Denable_ns3=ON -DNS3_HINT=/opt/ns3 # or change the path if needed
  42
  43 By the end of the configuration, cmake reports whether ns-3 was found,
  44 and this information is also available in ``include/simgrid/config.h``
  45 If your local copy defines the variable ``SIMGRID_HAVE_NS3`` to 1, then ns-3
  46 was correctly detected. Otherwise, explore ``CMakeFiles/CMakeOutput.log`` and
  47 ``CMakeFiles/CMakeError.log`` to diagnose the problem.
  48
  49 Test that ns-3 was successfully integrated with the following (from your SimGrid
  50 build directory). It will run all SimGrid tests that are related to the ns-3
  51 integration. If no test is run at all, you probably forgot to enable ns-3 in cmake.
  52
  53 .. code-block:: shell
  54
  55    ctest -R ns3
  56
  57 Troubleshooting
  58 ===============
  59
  60 If you use a version of ns-3 that is not known to SimGrid yet, edit
  61 ``tools/cmake/Modules/FindNS3.cmake`` in your SimGrid tree, according to the
  62 comments on top of this file. Conversely, if something goes wrong with an old
  63 version of either SimGrid or ns-3, try upgrading everything.
  64
  65 .. _ns3_use:
  66
  67 Using ns-3 from SimGrid
  68 ***********************
  69
  70 Platform files compatibility
  71 ============================
  72
  73 Any route longer than one will be ignored when using ns-3. They are
  74 harmless, but you still need to connect your hosts using one-hop routes.
  75 The best solution is to add routers to split your route. Here is an
  76 example of an invalid platform:
  77
  78 .. code-block:: xml
  79
  80    <?xml version='1.0'?>
  81    <!DOCTYPE platform SYSTEM "https://simgrid.org/simgrid.dtd">
  82    <platform version="4.1">
  83      <zone id="zone0" routing="Floyd">
  84        <host id="alice" speed="1Gf" />
  85        <host id="bob"   speed="1Gf" />
  86
  87        <link id="l1" bandwidth="1Mbps" latency="5ms" />
  88        <link id="l2" bandwidth="1Mbps" latency="5ms" />
  89
  90        <route src="alice" dst="bob">
  91          <link_ctn id="l1"/>            <!-- !!!! IGNORED WHEN USED WITH ns-3       !!!! -->
  92          <link_ctn id="l2"/>            <!-- !!!! ROUTES MUST CONTAIN ONE LINK ONLY !!!! -->
  93        </route>
  94      </zone>
  95    </platform>
  96
  97 This can be reformulated as follows to make it usable with the ns-3 binding.
  98 There is no direct connection from alice to bob, but that's OK because ns-3
  99 automatically routes from point to point (using
 100 ``ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables``).
 101
 102 .. code-block:: xml
 103
 104    <?xml version='1.0'?>
 105    <!DOCTYPE platform SYSTEM "https://simgrid.org/simgrid.dtd">
 106    <platform version="4.1">
 107      <zone id="zone0" routing="Full">
 108        <host id="alice" speed="1Gf" />
 109        <host id="bob"   speed="1Gf" />
 110
 111        <router id="r1" /> <!-- routers are compute-less hosts -->
 112
 113        <link id="l1" bandwidth="1Mbps" latency="5ms"/>
 114        <link id="l2" bandwidth="1Mbps" latency="5ms"/>
 115
 116        <route src="alice" dst="r1">
 117          <link_ctn id="l1"/>
 118        </route>
 119
 120        <route src="r1" dst="bob">
 121          <link_ctn id="l2"/>
 122        </route>
 123      </zone>
 124    </platform>
 125
 126 Once your platform is OK, just change the :ref:`network/model
 127 <options_model_select>` configuration option to `ns-3` as follows. The other
 128 options can be used as usual.
 129
 130 .. code-block:: shell
 131
 132    ./network-ns3 --cfg=network/model:ns-3 (other parameters)
 133
 134 Many other files from the ``examples/platform`` directory are usable with the
 135 ns-3 model, such as `examples/platforms/dogbone.xml <https://framagit.org/simgrid/simgrid/tree/master/examples/platforms/dogbone.xml>`_.
 136 Check the file  `examples/s4u/network-ns3/network-ns3.tesh <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/network-ns3/network-ns3.tesh>`_
 137 to see which ones are used in our regression tests.
 138
 139 WiFi platforms
 140 --------------
 141
 142 In SimGrid, WiFi networks are modeled with WiFi zones, where a zone contains
 143 the access point of the WiFi network and the hosts connected to it (called
 144 station in the WiFi world). Links inside WiFi zones are modeled as regular
 145 links with a specific attribute, and these links are then added to routes
 146 between hosts. The main difference When using ns-3 WiFi networks is that
 147 the network performance is not given by the link bandwidth and latency but
 148 by the access point WiFi characteristics, and the distance between the access
 149 point and the hosts.
 150
 151 So, to declare a new WiFi network, simply declare a zone with the ``WIFI``
 152 routing.
 153
 154 .. code-block:: xml
 155
 156         <zone id="SSID_1" routing="WIFI">
 157
 158 Inside this zone you must declare which host or router will be the access point
 159 of the WiFi network.
 160
 161 .. code-block:: xml
 162
 163         <prop id="access_point" value="alice"/>
 164
 165 Afterward simply declare the hosts and routers inside the WiFi network. Remember
 166 that one must have the same name as declared in the property "access point".
 167
 168 .. code-block:: xml
 169
 170         <router id="alice" speed="1Gf"/>
 171         <host id="STA0-0" speed="1Gf"/>
 172         <host id="STA0-1" speed="1Gf"/>
 173
 174 Finally, close the WiFi zone.
 175
 176 .. code-block:: xml
 177
 178         </zone>
 179
 180 The WiFi zone may be connected to another zone using a traditional link and
 181 a zoneRoute. Note that the connection between two zones is always wired.
 182
 183 .. code-block:: xml
 184
 185         <link id="wireline" bandwidth="100Mbps" latency="2ms" sharing_policy="SHARED"/>
 186
 187         <zoneRoute src="SSID_1" dst="SSID_2" gw_src="alice" gw_dst="bob">
 188             <link_ctn id="wireline"/>
 189         </zoneRoute>
 190
 191 WiFi network performance
 192 ^^^^^^^^^^^^^^^^^^^^^^^^
 193
 194
 195 The performance of a wifi network is controlled by 3 property that can be added
 196 to hosts connected to the wifi zone:
 197
 198  * ``mcs`` (`Modulation and Coding Scheme <https://en.wikipedia.org/wiki/Link_adaptation>`_)
 199    Roughly speaking, it defines the speed at which the access point is
 200    exchanging data with all stations. It depends on its model and configuration,
 201    and the possible values are listed for example on Wikipedia.
 202    |br| By default, ``mcs=3``.
 203    It is a property of the WiFi zone.
 204  * ``nss`` (Number of Spatial Streams, or `number of antennas <https://en.wikipedia.org/wiki/IEEE_802.11n-2009#Number_of_antennas>`_)
 205    defines the amount of simultaneous data streams that the AP can sustain.
 206    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>`_).
 207    |br| By default, ``nss=1``.
 208    It is a property of the WiFi zone.
 209  * ``wifi_distance`` is the distance from the station to the access point. Each
 210    station can have a specific value.
 211    |br| By default, ``wifi_distance=10``.
 212    It is a property of stations of the WiFi network.
 213
 214 Here is an example of a zone changing ``mcs`` and ``nss`` values.
 215
 216 .. code-block:: xml
 217
 218         <zone id="SSID_1" routing="WIFI">
 219             <prop id="access_point" value="alice"/>
 220             <prop id="mcs" value="2"/>
 221             <prop id="nss" value="2"/>
 222         ...
 223         </zone>
 224
 225 Here is an example of a host changing ``wifi_distance`` value.
 226
 227 .. code-block:: xml
 228
 229         <host id="STA0-0" speed="1Gf">
 230             <prop id="wifi_distance" value="37"/>
 231         </host>
 232
 233 Random Number Generator
 234 =======================
 235
 236 It is possible to define a fixed or random seed to the ns3 random number
 237 generator using the config tag.
 238
 239 .. code-block:: xml
 240
 241         <?xml version='1.0'?><!DOCTYPE platform SYSTEM "https://simgrid.org/simgrid.dtd">
 242         <platform version="4.1">
 243             <config>
 244                     <prop id = "network/model" value = "ns-3" />
 245                     <prop id = "ns3/seed" value = "time" />
 246             </config>
 247         ...
 248         </platform>
 249
 250 The first property defines that this platform will be used with the ns3 model.
 251 The second property defines the seed that will be used. Defined to ``time``
 252 it will use a random seed, defined to a number it will use this number as
 253 the seed.
 254
 255 Limitations
 256 ===========
 257
 258 A ns-3 platform is automatically created from the provided SimGrid
 259 platform. However, there are some known caveats:
 260
 261   * The default values (e.g., TCP parameters) are the ns-3 default values.
 262   * ns-3 networks are routed using the shortest path algorithm, using ``ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables``.
 263   * End hosts cannot have more than one interface card. So, your SimGrid hosts
 264     should be connected to the platform through only one link. Otherwise, your
 265     SimGrid host will be considered as a router (FIXME: is it still true?).
 266
 267 Our goal is to keep the ns-3 plugin of SimGrid as easy (and hopefully readable)
 268 as possible. If the current state does not fit your needs, you should modify
 269 this plugin, and/or create your own plugin from the existing one. If you come up
 270 with interesting improvements, please contribute them back.
 271
 272 Troubleshooting
 273 ===============
 274
 275 If your simulation hangs in a communication, this is probably because one host
 276 is sending data that is not routable in your platform. Make sure that you only
 277 use routes of length 1, and that any host is connected to the platform.
 278 Arguably, SimGrid could detect this situation and report it, but unfortunately,
 279 this is still to be done.
 280
 281 .. |br| raw:: html
 282
 283    <br />