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 HAVE_NS3 to 1, then NS3
  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 \subsection pls_ns3_config_trouble Troubleshooting
  58
  59 If you have a ns-3 version that is not known to SimGrid yet, edit \c
  60 tools/cmake/Modules/FindNS3.cmake in your SimGrid tree, according to
  61 the comments on top of this file.
  62
  63 If the compilation fails on Debian/Ubuntu when linking the library
  64 because of some .a file that cannot be used dynamically, then you are
  65 probably using a very old (and buggy) <tt>libns3-dev</tt>
  66 package. Update it, or install <tt>libns3-3</tt> manually.
  67
  68 \section pls_ns3_use Using ns-3 from SimGrid
  69
  70 The SimGrid-ns3 binding only contains features that are common to both
  71 systems: ns-3 wireless models are not available, while SimGrid routes
  72 cannot be longer than 1. Also, the platform built in ns-3 from the
  73 SimGrid description is very basic.
  74
  75 If your platform have longer routes, simply add some routers to break
  76 these routes. SimGrid's routers are similar to hosts, without
  77 computational abilities.
  78
  79 Once your platform is OK, just change the "network/model"
  80 configuration option to "NS3". The rest remains unchanged.
  81
  82 The following should work from the examples/msg/network-ns3 folder,
  83 where the \c network-ns3 binary example lives.
  84
  85 \verbatim
  86 ./network-ns3 ../../platforms/small_platform_one_link_routes.xml 3hosts_2links_d.xml --cfg=network/model:NS3 --log=root.threshold:info
  87 \endverbatim
  88
  89 Many other files from the examples/platform directory are usable with
  90 the ns-3 model. Check the file
  91 examples/msg/network-ns3/network-ns3.tesh to see which ones are used
  92 in our regression tests. You may also be interested in the
  93 @ref msg_ex_ns3 "ns-3/SimGrid examples".
  94
  95 A ns-3 platform is automatically created from the provided SimGrid
  96 platform. However, there are some known caveats:
  97
  98 <ul>
  99
 100   <li>The default values (e.g., TCP parameters) are the ns3 default
 101       values.</li>
 102
 103   <li>ns-3 networks are routed using the shortest path algorithm, using
 104       ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables.</li>
 105
 106   <li>End hosts cannot have more than one interface card. So, your
 107       SimGrid hosts should be connected to the platform through only
 108       one link. Otherwise, your SimGrid host will be considered as a
 109       router.</li>
 110
 111 </ul>
 112
 113 Our goal is to keep the ns-3 plugin of SimGrid as easy (and hopefully
 114 readable) as possible. If the current state does not fit your needs,
 115 you should modify this plugin, and/or create your own plugin from the
 116 existing one.
 117
 118 */