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
  60 both systems. Not all ns-3 models are available (only the TCP and wifi
  61 ones are), while not all SimGrid platform file can be used with ns-3
  62 (routes must be of length 1). Also, the platform built in ns-3 from
  63 the SimGrid description is very basic.
  64
  65 Platform files compatibility
  66 ============================
  67
  68 Any route longer than one will be ignored when using ns-3. They are
  69 harmless, but you still need to connect your hosts using one-hop routes.
  70 The best solution is to add routers to split your route. Here is an
  71 example of an invalid platform:
  72
  73 .. code-block:: shell
  74
  75    <?xml version='1.0'?>
  76    <!DOCTYPE platform SYSTEM "https://simgrid.org/simgrid.dtd">
  77    <platform version="4.1">
  78      <zone id="zone0" routing="Floyd">
  79        <host id="alice" speed="1Gf" />
  80        <host id="bob"   speed="1Gf" />
  81
  82        <link id="l1" bandwidth="1Mbps" latency="5ms" />
  83        <link id="l2" bandwidth="1Mbps" latency="5ms" />
  84
  85        <route src="alice" dst="bob">
  86          <link_ctn id="l1"/>            <!-- !!!! INVALID WITH ns-3    !!!! -->
  87          <link_ctn id="l2"/>            <!-- !!!! length=2 IS TOO MUCH !!!! -->
  88        </route>
  89      </zone>
  90    </platform>
  91
  92 This can be reformulated as follows to make it usable with the ns-3 binding.
  93 There is no direct connection from alice to bob, but that's OK because
  94 ns-3 automatically routes from point to point.
  95
  96 .. code-block:: shell
  97
  98    <?xml version='1.0'?>
  99    <!DOCTYPE platform SYSTEM "https://simgrid.org/simgrid.dtd">
 100    <platform version="4.1">
 101      <zone id="zone0" routing="Full">
 102        <host id="alice" speed="1Gf" />
 103        <host id="bob"   speed="1Gf" />
 104
 105        <router id="r1" /> <!-- routers are compute-less hosts -->
 106
 107        <link id="l1" bandwidth="1Mbps" latency="5ms"/>
 108        <link id="l2" bandwidth="1Mbps" latency="5ms"/>
 109
 110        <route src="alice" dst="r1">
 111          <link_ctn id="l1"/>
 112        </route>
 113
 114        <route src="r1" dst="bob">
 115          <link_ctn id="l2"/>
 116        </route>
 117      </zone>
 118    </platform>
 119
 120 Once your platform is OK, just change the :ref:`network/model
 121 <options_model_select>`_ configuration option to "ns-3" as follows. The rest
 122 is unchanged.
 123
 124 .. code-block:: shell
 125
 126    ./network-ns3 --cfg=network/model:ns-3 (other parameters)
 127
 128 Many other files from the ``examples/platform directory`` are usable with the
 129 ns-3 model, such as `examples/platforms/dogbone.xml <https://framagit.org/simgrid/simgrid/tree/master/examples/platforms/dogbone.xml>`_.
 130 Check the file  `examples/s4u/network-ns3/network-ns3.tesh <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/network-ns3/network-ns3.tesh>`_
 131 to see which ones are used in our regression tests.
 132
 133 Build a wifi-compatible platform
 134 ===================================
 135
 136 We describe here a simple platform allowing ns3 wifi communication
 137 between two SimGrid hosts.
 138
 139 First, here are the mandatory information necessary to create a
 140 simgrid platform:
 141
 142 .. code-block:: shell
 143
 144         <?xml version='1.0'?>
 145         <!DOCTYPE platform SYSTEM "http://simgrid.org/simgrid.dtd">
 146         <platform version="4.1">
 147                 <zone id="zone" routing="Floyd">
 148
 149 Then, we create our access point and station hosts:
 150
 151 .. code-block:: shell
 152
 153                         <host id="alice" speed="1Gf"/>
 154                         <host id="bob"   speed="1Gf"/>
 155
 156 We must specify that alice will be our access point. To do that we
 157 simply add the property ``wifi_link`` to the host ``alice``:
 158
 159 .. code-block:: shell
 160
 161                         <host id="alice" speed="1Gf">
 162                                 <prop id="wifi_link" value="net0"/>
 163                         </host>
 164
 165                         <host id="bob"   speed="1Gf"/>
 166
 167 The value ``net0`` of this property defines the name of the wifi network
 168 generated. To generate this wifi network we create a wifi link:
 169
 170 .. code-block:: shell
 171
 172                         <link id="net0" bandwidth="0" latency="0" sharing_policy="WIFI"/>
 173
 174 The important information here are:
 175         * The id of the link, ``net0``, must match the network name defined by the property ``wifi_link`` of the access point node
 176         * The sharing policy must be set to ``WIFI``
 177
 178 Note: bandwidth and latency are mandatory by simgrid to create a link but are NOT used to create a wifi network. Instead the
 179 wifi network capabilities are defined by its MCS, NSS and distance from access point to station. Those properties are described in section :ref:`Optional access point node properties <optional_prop>`_
 180
 181 To connect the station node to the access point node, we
 182 create a route between the hosts:
 183
 184 .. code-block:: shell
 185
 186                         <route src="alice" dst="bob">
 187                                 <link_ctn id="net0" />
 188                         </route>
 189
 190 Finally, we end the xml file with the missing closing tags:
 191
 192 .. code-block:: shell
 193
 194                 </zone>
 195         </platform>
 196
 197 .. _optional_prop:
 198
 199 Optional access point node properties
 200 --------------------------------------
 201
 202 The MCS (`Modulation and Coding Scheme <https://en.wikipedia.org/wiki/Link_adaptation>`_) can be set with the property ``wifi_mcs``:
 203
 204 .. code-block:: shell
 205
 206                          <host id="alice" speed="1Gf">
 207                                 <prop id="wifi_link" value="net0"/>
 208                                 <prop id="wifi_mcs" value="5"/>
 209                         </host>
 210
 211 Its default value is 3.
 212
 213 The NSS (Number of Spatial Streams, also known as the `number of antennas <https://en.wikipedia.org/wiki/IEEE_802.11n-2009#Number_of_antennas>`_) can be set with the property ``wifi_nss``:
 214
 215 .. code-block:: shell
 216
 217                         <host id="alice" speed="1Gf">
 218                                 <prop id="wifi_link" value="net0"/>
 219                                 <prop id="wifi_nss" value="2"/>
 220                         </host>
 221
 222 Its default value is 1.
 223
 224 Note: not all value of MCS and NSS are valid nor compatible. Check `802.11n standard <https://en.wikipedia.org/wiki/IEEE_802.11n-2009#Data_rates>`_ for more information.
 225
 226 Optional station node properties
 227 ---------------------------------
 228
 229 The distance in meter at which the station is placed from the access point can
 230 be set with the property ``wifi_distance``.
 231
 232 .. code-block:: shell
 233
 234                         <host id="alice" speed="100.0Mf,50.0Mf,20.0Mf" pstate="0">
 235                                 <prop id="wifi_distance" value="30" />
 236                         </host>
 237
 238 Its default value is 10.
 239
 240 Limitations
 241 ===========
 242
 243 A ns-3 platform is automatically created from the provided SimGrid
 244 platform. However, there are some known caveats:
 245
 246         * The default values (e.g., TCP parameters) are the ns-3 default values.
 247         * ns-3 networks are routed using the shortest path algorithm, using
 248                 ``ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables``.
 249         * End hosts cannot have more than one interface card. So, your
 250           SimGrid hosts should be connected to the platform through only
 251           one link. Otherwise, your SimGrid host will be considered as a
 252           router (FIXME: is it still true?).
 253
 254 Our goal is to keep the ns-3 plugin of SimGrid as easy (and hopefully readable)
 255 as possible. If the current state does not fit your needs, you should modify
 256 this plugin, and/or create your own plugin from the existing one. If you come up
 257 with interesting improvements, please contribute them back.
 258
 259 Troubleshooting
 260 ===============
 261
 262 If your simulation hangs in a communication, this is probably because one host
 263 is sending data that is not routable in your platform. Make sure that you only
 264 use routes of length 1, and that any host is connected to the platform.
 265 Arguably, SimGrid could detect this situation and report it, but unfortunately,
 266 this is still to be done.