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