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