doc/doxygen/pls.doc

   1 /*! \page pls Packet level simulation
   2
   3 \tableofcontents
   4
   5 It is possible to use a packet-level network simulator instead of the default flow-based models. You may want to use
   6 this feature if you have doubts about the validity of the default model or want to perform some validation experiments.
   7
   8 At the moment, we support the well-known <a href="http://www.nsnam.org/"><b>ns-3</b></a> packet-level simulator. Earlier
   9 releases of SimGrid did support the <b>GTNetS</b> simulator. Its support could possibly be revived by someone who would
  10 need it.
  11
  12 \section pls_simgrid_configuration_ns3 ns-3 as a SimGrid model
  13
  14 This section explains how  to replace the SimGrid network models by those of the well-known
  15 <a href="http://www.nsnam.org/">ns-3</a> packet-level network simulator.
  16
  17 \subsection pls_simgrid_configuration_ns3_install Installing ns-3
  18
  19 The easiest is to install it with the package manager. Under Debian/Ubuntu, simply type as root:
  20
  21 \verbatim
  22 apt-get install libns3-dev ns3
  23 \endverbatim
  24
  25 You can also install it from scratch with the following commands:
  26
  27 \verbatim
  28 # Download the source
  29 wget http://www.nsnam.org/release/ns-allinone-3.25.tar.bz2
  30 tar -xf ns-allinone-3.25.tar.bz2
  31 cd ns-allinone-3.25/ns-3.25/
  32 # Configure, build and install
  33 ./waf configure --prefix="/opt/ns3" # or give another path if you prefer
  34 ./waf
  35 ./waf install
  36 \endverbatim
  37
  38 For more information, please refer to the ns-3 documentation.
  39
  40 \subsection pls_simgrid_configuration_ns3_config Enabling SimGrid's support for ns-3
  41
  42 Normally, you just have to enable ns-3 in ccmake or cmake as follows. If you installed ns-3 in a regular path, just
  43 drop the ns3_path configuration item.
  44
  45 \verbatim
  46 cmake . -Denable_ns3=ON -DNS3_HINT=/opt/ns3 # or change the path if needed
  47 \endverbatim
  48
  49 By the end of the configuration, cmake reports whether ns-3 was found. You can also double-check by executing the tests
  50 after the compilation.
  51
  52 \verbatim
  53 $ ctest -R ns3
  54 (test(s) should be run)
  55 \endverbatim
  56
  57 If you have a ns-3 version that is not known to SimGrid (yet), the detection may fail. In that case, edit the
  58 tools/cmake/Modules/FindNS3.cmake file in your SimGrid tree. The
  59 required changes are very easy, and documented in the file header.
  60
  61 If the compilation fails when linking the library because of some .a file that cannot be used dynamically, this is
  62 probably because you only installed the libns3-dev library on your Debian, where you also need libns3-3. This is
  63 probably a bug of the libns3-dev package that should depend on the dynamic libraries corresponding to its .so files.
  64
  65 \subsection pls_simgrid_configuration_ns3_use Using ns-3 from SimGrid
  66
  67 A working example of ns-3/SimGrid interactions can be found in examples/msg/network-ns3/. Basically, you just have to
  68 run your SimGrid simulation with the configuration option "network/model" set to "NS3". The rest remains unchanged.
  69
  70 The following should work from the examples/msg/network-ns3 folder (network-ns3 is the name of our example binary).
  71
  72 \verbatim
  73 ./network-ns3 ./3hosts_2links_p.xml 3hosts_2links_d.xml --cfg=network/model:NS3 --log=root.threshold:info
  74 \endverbatim
  75
  76 A ns-3 platform is automatically created from the provided SimGrid platform file. However, there are some known caveats:
  77
  78 <ul>
  79   <li>The default values (e.g., TCP parameters) are the ns3  values. Don't blame us for them.</li>
  80
  81   <li>ns-3 networks are routed using the shortest path algorithm, using
  82    ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables.</li>
  83
  84   <li>End hosts cannot have more than one interface card (so, only one &lt;link&gt; in your SimGrid platform should
  85    link an end host to the platform ; if not, your end host will be considered as a router.  </li>
  86 </ul>
  87
  88 More about ns-3 simulator <a href="http://www.nsnam.org/">(Official website)</a>
  89
  90 \subsection ns3_examples Examples
  91
  92 For an example using NS3 as a SimGrid module, please refer to the
  93 @ref msg_ex_ns3 "relevant section" of the documentation.
  94
  95 */