doc/doxygen/ns3.doc

   1 /*! \page pls_ns3 ns-3 as a SimGrid model
   2
   3 \tableofcontents
   4
   5 You can use the well-known
   6 <a href="http://www.nsnam.org/"><b>ns-3</b></a> packet-level network
   7 simulator as a SimGrid model, for example to investigate the validity
   8 of your simulation. Just install ns-3 and recompile SimGrid accordingly.
   9
  10 \section pls_ns3_install Installing ns-3
  11
  12 The easiest is to install it with the package manager. Under Debian/Ubuntu, simply type as root:
  13
  14 \verbatim
  15 apt-get install libns3-dev ns3
  16 \endverbatim
  17
  18 You can also install it from scratch with the following commands:
  19
  20 \verbatim
  21 # Download the source
  22 wget http://www.nsnam.org/release/ns-allinone-3.26.tar.bz2
  23 tar -xf ns-allinone-3.26.tar.bz2
  24 cd ns-allinone-3.26/ns-3.26/
  25 # Configure, build and install
  26 ./waf configure --prefix="/opt/ns3" # or give another path if you prefer
  27 ./waf
  28 ./waf install
  29 \endverbatim
  30
  31 For more information, please refer to the ns-3 documentation
  32 <a href="http://www.nsnam.org/">(official website)</a>.
  33
  34 \section pls_ns3_config Enabling SimGrid's support for ns-3
  35
  36 Normally, you just have to enable ns-3 in ccmake or cmake as
  37 follows. If you installed ns-3 in a regular path, just drop the
  38 NS3_HINT configuration item.
  39
  40 \verbatim
  41 cmake . -Denable_ns3=ON -DNS3_HINT=/opt/ns3 # or change the path if needed
  42 \endverbatim
  43
  44 By the end of the configuration, cmake reports whether ns-3 was found,
  45 and this information is also available in <tt>include/simgrid_config.h</tt>
  46 If your local copy defines the variable \c SIMGRID_HAVE_NS3 to 1, then ns-3
  47 was correctly detected. If it's defined to 0, then something went
  48 wrong. Explore <tt>CMakeFiles/CMakeOutput.log</tt> and
  49 <tt>CMakeFiles/CMakeError.log</tt> to diagnose the problem.
  50
  51 Afterward, you can test your installation as follows:
  52
  53 \verbatim
  54 $ ctest -R ns3
  55 \endverbatim
  56
  57 \section pls_ns3_use Using ns-3 from SimGrid
  58
  59 The SimGrid-ns3 binding only contains features that are common to both
  60 systems: ns-3 wireless models are not available, while SimGrid routes
  61 cannot be longer than 1. Also, the platform built in ns-3 from the
  62 SimGrid description is very basic.
  63
  64 Any route longer than one will be ignored when using ns-3. They are
  65 harmless, but you still need to connect your hosts using one-hop routes.
  66 The best solution is to add routers to split your route. Here is an
  67 example of invalid platform:
  68
  69 @code{.xml}
  70 <platform>
  71   <host id="alice" speed="1Gf" />
  72   <host id="bob"   speed="1Gf" />
  73
  74   <link id="l1" bw="1Mbps" />
  75   <link id="l2" bw="1Mbps" />
  76
  77   <route src="alice" dst="bob">
  78     <link_ctn id="l1"/> <!-- INVALID WITH NS-3 -->
  79     <link_ctn id="l2"/> <!-- length=2 IS TOO MUCH -->
  80   </route>
  81 </platform>
  82 @endcode
  83
  84 Here is the same platform expressed in a way that ns-3 will understand.
  85 There is no direct connexion from alice to bob, but that's OK because
  86 ns-3 will find the path from point to point.
  87
  88 @code{.xml}
  89 <platform>
  90   <host id="alice" speed="1Gf" />
  91   <host id="bob"   speed="1Gf" />
  92
  93   <router id="r1" /> <!-- routers are compute-less hosts -->
  94
  95   <link id="l1" bw="1Mbps" />
  96   <link id="l2" bw="1Mbps" />
  97
  98   <route src="alice" dst="r1">
  99     <link_ctn id="l1"/>
 100   </route>
 101
 102   <route src="r1" dst="bob">
 103     <link_ctn id="l2"/>
 104   </route>
 105 </platform>
 106 @endcode
 107
 108
 109 Once your platform is OK, just change the "network/model"
 110 configuration option to "NS3" as follows. The rest remains unchanged.
 111
 112 \verbatim
 113 ./network-ns3 ../../platforms/small_platform_one_link_routes.xml 3hosts_2links_d.xml --cfg=network/model:NS3
 114 \endverbatim
 115
 116 Many other files from the examples/platform directory are usable with
 117 the ns-3 model, such as @ref examples/platforms/dogbone.xml. Check the file
 118 examples/msg/network-ns3/network-ns3.tesh to see which ones are used
 119 in our regression tests. You may also be interested in the
 120 @ref msg_ex_ns3 "ns-3/SimGrid examples".
 121
 122 @subsection pls_ns3_shortcomings Shortcomings of the ns-3 bindings in SimGrid
 123
 124 A ns-3 platform is automatically created from the provided SimGrid
 125 platform. However, there are some known caveats:
 126
 127 <ul>
 128
 129   <li>The default values (e.g., TCP parameters) are the ns3 default
 130       values.</li>
 131
 132   <li>ns-3 networks are routed using the shortest path algorithm, using
 133       ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables.</li>
 134
 135   <li>End hosts cannot have more than one interface card. So, your
 136       SimGrid hosts should be connected to the platform through only
 137       one link. Otherwise, your SimGrid host will be considered as a
 138       router.</li>
 139
 140 </ul>
 141
 142 Our goal is to keep the ns-3 plugin of SimGrid as easy (and hopefully
 143 readable) as possible. If the current state does not fit your needs,
 144 you should modify this plugin, and/or create your own plugin from the
 145 existing one.
 146
 147 @section pls_trouble Troubleshooting with ns-3 and SimGrid
 148
 149 @subsection pls_ns3_config_trouble I fail to compile ns-3 within SimGrid
 150
 151 If you have a ns-3 version that is not known to SimGrid yet, edit \c
 152 tools/cmake/Modules/FindNS3.cmake in your SimGrid tree, according to
 153 the comments on top of this file.
 154
 155 If the compilation fails on Debian/Ubuntu when linking the library
 156 because of some .a file that cannot be used dynamically, then you are
 157 probably using a very old (and buggy) <tt>libns3-dev</tt>
 158 package. Update it, or install <tt>libns3-3</tt> manually.
 159
 160 @subsection pls_trouble_hang The simulation hangs at some point
 161
 162 If your simulation hangs in a communication, this is probably because
 163 one host is sending data that is not routable in your platform. Make
 164 sure that you only use routes of length 1, and that any host is
 165 connected to the platform.
 166
 167 Arguably, SimGrid could detect this situation and report it, but
 168 unfortunately, this is still to be done.
 169
 170 @subsection pls_trouble_warning I get a warning that some routes are ignored
 171
 172 Please read again the @ref pls_ns3_use section.
 173
 174
 175 @example examples/platforms/dogbone.xml
 176 */