doc/doxygen/pls.doc

   1 /*! \page pls Packet level simulation
   2
   3 It is possible to use a packet-level network simulator
   4 instead of the default flow-based simulation. You may want to use such
   5 an approach if you have doubts about the validity of the default model
   6 or if you want to perform some validation experiments. At the moment,
   7 we support the NS3 and GTNetS simulators.
   8
   9
  10 \section pls_simgrid_configuration_gtnets GTNetS as a SimGrid model
  11
  12 \subsection pls_simgrid_configuration_gtnets_compile Compiling a patched version of  GTNetS
  13
  14 GTNetS needs to be patched to work with SimGrid, so the easiest
  15 solution is to run the following commands:
  16
  17 \verbatim
  18 # Get the files that we prepared for you
  19 svn checkout svn://scm.gforge.inria.fr/svn/simgrid/contrib/trunk/GTNetS/
  20 cd GTNetS
  21
  22 # Unpack and patch the sources
  23 unzip gtnets-current.zip
  24 tar zxvf gtnets-current-patch.tgz
  25 cd gtnets-current
  26 cat ../*.patch | patch -p1
  27
  28 # Compile GTNetS
  29 ln -sf Makefile.linux Makefile
  30 sed -i 's/-fPIC/-fPIC -fpermissive/g' Makefile
  31 make depend
  32 make opt   # compile an optimized version (required)
  33 make debug # compile a debug version (optional)
  34
  35 # Install under /opt
  36 mkdir -p /opt/gtnets/include /opt/gtnets/lib
  37 cp -fr SRC/*.h /opt/gtnets/include
  38 cp libgtsim-opt.so /opt/gtnets/lib/libgtsim.so
  39 \endverbatim
  40
  41 Some remarks:
  42
  43 <ul>
  44
  45   <li>The patch
  46    AMD64-FATAL-Removed-DUL_SIZE_DIFF-Added-fPIC-compillin.patch is
  47    only useful if you want to compile on Itanium 64bits (but should be
  48    harmless on other architectures). Note that we only provide support
  49    for Linux so far.  Your patches are welcome to improve this ;)</li>
  50
  51   <li>The compilation spits a lot of warnings, but the application
  52    should compile by the end. If the makefile insists in compiling
  53    some QT libraries please try a make clean before asking for help.</li>
  54
  55   <li>If you need to use another version of GTNetS, then you will
  56    probably need to modify the patch. Please drop us a line: we will
  57    gratefully integrate your work. For the record, the version that we
  58    provide were downloaded from <a href="http://www.ece.gatech.edu/research/labs/MANIACS/GTNetS/software/gtnets-current.zip">here</a>
  59    on June 12th, 2008.</li>
  60
  61   <li>Of course you can install GTNets wherever you want on your hard
  62    disk. We provide the commands for /opt just to help you.</li>
  63 </ul>
  64
  65 Add the following to your .bashrc so that it gets defined each time:
  66
  67 \verbatim
  68 export LD_LIBRARY_PATH=${LD_LIBRARY_PATH:+$LD_LIBRARY_PATH:}/opt/gtnets/lib/
  69 \endverbatim
  70
  71 \subsection pls_simgrid_configuration_gtnets_config Enabling SimGrid's support for GTNetS
  72
  73 You just have to enable GTNetS in ccmake or cmake as follows, and
  74 recompile SimGrid.
  75
  76 \verbatim
  77 cmake . -Denable_gtnets=ON -Dgtnets_path=/opt/gtnets
  78 \endverbatim
  79
  80 By the end of the configuration, cmake reports whether GTNetS was found.
  81 You can also double-check by executing the tests after the compilation.
  82
  83 \verbatim
  84 $ ctest -R gtnets
  85 (several tests should be run)
  86 \endverbatim
  87
  88 \subsection pls_simgrid_configuration_gtnets_use Using GTNetS from SimGrid
  89
  90 A working example can be found in the folder examples/msg/gtnets.
  91
  92 \verbatim
  93 gtnets/gtnets gtnets/onelink-p.xml gtnets/onelink-d.xml --cfg=network/model:GTNets
  94 \endverbatim
  95
  96 For more information, please refer to the <a
  97 href="http://www.ece.gatech.edu/research/labs/MANIACS/GTNetS/index.html">GTNetS
  98 Website</a> or to this
  99 <a href="http://gforge.inria.fr/docman/view.php/12/6283/GTNetS
 100 HowTo.html">possibly outdated longer HowTo</a>
 101
 102 \section pls_simgrid_configuration_ns3 NS3 as a SimGrid model
 103
 104 You may want to replace the SimGrid network models by the ones of the
 105 well known packet-level network simulator <a href="http://www.nsnam.org/">NS-3</a> instead.
 106 This section explains how to do so.
 107
 108 \subsection pls_simgrid_configuration_ns3_install Installing NS3
 109
 110 The easiest is to install it with the package manager.  Under
 111 Debian/Ubuntu, simply type as root:
 112
 113 \verbatim
 114 apt-get install libns3-dev ns3
 115 \endverbatim
 116
 117 You can also install it from scratch with the following commands:
 118
 119 \verbatim
 120 # Download the source
 121 wget http://www.nsnam.org/release/ns-allinone-3.22.tar.bz2
 122 tar -xf ns-allinone-3.22.tar.bz2
 123 cd ns-allinone-3.22/ns-3.22/
 124 # Configure, build and install
 125 ./waf configure --prefix="ns-3_install_directory"
 126 ./waf
 127 ./waf install
 128 \endverbatim
 129
 130 For more information, please refer to the NS-3 documentation.
 131
 132 \subsection pls_simgrid_configuration_ns3_config Enabling SimGrid's support for NS3
 133
 134 Normally, you just have to enable NS3 in ccmake or cmake as follows.
 135 If you installed NS3 in a regular path, just drop the ns3_path
 136 configuration item.
 137
 138 \verbatim
 139 cmake . -Denable_ns3=ON -Dns3_path=<ns3_path>
 140 \endverbatim
 141
 142 By the end of the configuration, cmake reports whether NS-3 was found.
 143 You can also double-check by executing the tests after the compilation.
 144
 145 \verbatim
 146 $ ctest -R ns3
 147 (several tests should be run)
 148 \endverbatim
 149
 150 If you have a NS3 version that is not known (yet) to SimGrid, the
 151 detection may fail. In that case, edit  the file
 152 buildtools/Cmake/Modules/FindNS3.cmake in your SimGrid tree. The
 153 required changes are very easy, and documented at the beginning of
 154 this file.
 155
 156 If the compilation fails when linking the library because of some .a
 157 file that cannot be used dynamically, that's probably because you only
 158 installed the libns3-dev library on your Debian, where you also need
 159 libns3-3. That's probably a bug of the libns3-dev package that should
 160 depend on the dynamic libraries corresponding to its .so files.
 161
 162 \subsection pls_simgrid_configuration_ns3_use Using NS3 from SimGrid
 163
 164 A working example of NS3/SimGrid interactions can be found in
 165 examples/msg/ns3. Basically, you just have to run your SimGrid
 166 simulation with the configuration option "network/model" set to the
 167 value "NS3". The rest remains unchanged.
 168
 169 The following should work from the examples/msg/ns3 folder (ns3 here
 170 is the name of our example binary).
 171
 172 \verbatim
 173 ./ns3 ./3hosts_2links_p.xml 3hosts_2links_d.xml --cfg=network/model:NS3 --log=root.threshold:info
 174 \endverbatim
 175
 176 A ns-3 platform is automatically created from the SimGrid platform
 177 file that you will provide. There is some caveats to know:
 178
 179 <ul>
 180   <li>The default values (e.g., TCP parameters) are the ns3
 181     values. Don't blame us for them.</li>
 182
 183   <li>NS3 networks are routed using the shortest path algorithm, using
 184     ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables.</li>
 185
 186   <li>End hosts cannot have more than one interface card (so, only one
 187    &lt;link&gt; in your SimGrid platform should link an end host to
 188    the platform ; if not, your end host will be considered as a
 189    router.  </li>
 190 </ul>
 191
 192
 193 More about ns-3 simulator <a href="http://www.nsnam.org/">(Official website)</a>
 194
 195 */