instead of the default flow-based simulation. You may want to use such
an approach if you have doubts about the validity of the default model
or if you want to perform some validation experiments. At the moment,
-we support the GTNetS simulator and since version 3.6.2, ns-3.
+we support the NS3 and GTNetS simulators.
-\section pls_simgrid_configuration_gtnets Using GTNetS
+\section pls_simgrid_configuration_gtnets GTNetS as a SimGrid model
+\subsection pls_simgrid_configuration_gtnets_compile Compiling a patched version of GTNetS
-<i>
-To enable GTNetS model inside SimGrid it is needed to patch the GTNetS simulator source code
-and build/install it from scratch
-</i>
-
- - <b>Download and enter the recent downloaded GTNetS directory</b>
+GTNetS needs to be patched to work with SimGrid, so the easiest
+solution is to run the following commands:
\verbatim
+# Get the files that we prepared for you
svn checkout svn://scm.gforge.inria.fr/svn/simgrid/contrib/trunk/GTNetS/
cd GTNetS
-\endverbatim
-
-
- - <b>Use the following commands to unzip and patch GTNetS package to work within SimGrid.</b>
-\verbatim
+# Unpack and patch the sources
unzip gtnets-current.zip
tar zxvf gtnets-current-patch.tgz
cd gtnets-current
-cat ../00*.patch | patch -p1
-\endverbatim
-
- - <b>OPTIONALLY</b> you can use a patch for itanium 64bit processor family.
+cat ../*.patch | patch -p1
-\verbatim
-cat ../AMD64-FATAL-Removed-DUL_SIZE_DIFF-Added-fPIC-compillin.patch | patch -p1
-\endverbatim
-
- - <b>Compile GTNetS</b>
-
- Due to portability issues it is possible that GTNetS does not compile in your architecture. The patches furnished in SimGrid SVN repository are intended for use in Linux architecture only. Unfortunately, we do not have the time, the money, neither the manpower to guarantee GTNetS portability. We advice you to use one of GTNetS communication channel to get more help in compiling GTNetS.
-
-
-\verbatim
+# Compile GTNetS
ln -sf Makefile.linux Makefile
sed -i 's/-fPIC/-fPIC -fpermissive/g' Makefile
make depend
-make debug
+make opt # compile an optimized version (required)
+make debug # compile a debug version (optional)
+
+# Install under /opt
+mkdir -p /opt/gtnets/include /opt/gtnets/lib
+cp -fr SRC/*.h /opt/gtnets/include
+cp libgtsim-opt.so /opt/gtnets/lib/libgtsim.so
\endverbatim
+Some remarks:
- - <b>NOTE</b> A lot of warnings are expected but the application should compile
- just fine. If the makefile insists in compiling some QT libraries
- please try a make clean before asking for help.
+<ul>
+ <li>The patch
+ AMD64-FATAL-Removed-DUL_SIZE_DIFF-Added-fPIC-compillin.patch is
+ only useful if you want to compile on Itanium 64bits (but should be
+ harmless on other architectures). Note that we only provide support
+ for Linux so far. Your patches are welcome to improve this ;)</li>
- - <b>To compile optimized version</b>
+ <li>The compilation spits a lot of warnings, but the application
+ should compile by the end. If the makefile insists in compiling
+ some QT libraries please try a make clean before asking for help.</li>
-\verbatim
-make opt
-\endverbatim
+ <li>If you need to use another version of GTNetS, then you will
+ probably need to modify the patch. Please drop us a line: we will
+ gratefully integrate your work. For the record, the version that we
+ provide were downloaded from <a href="http://www.ece.gatech.edu/research/labs/MANIACS/GTNetS/software/gtnets-current.zip">here</a>
+ on June 12th, 2008.</li>
+ <li>Of course you can install GTNets wherever you want on your hard
+ disk. We provide the commands for /opt just to help you.</li>
+</ul>
- - <b>Installing GTNetS</b>
-
- It is important to put the full path of your libgtsim-xxxx.so file when creating the symbolic link. Replace < userhome > by some path you have write access to.
+Add the following to your .bashrc so that it gets defined each time:
\verbatim
-ln -sf /<absolute_path>/gtnets_current/libgtsim-debug.so /<userhome>/usr/lib/libgtnets.so
-export LD_LIBRARY_PATH=${LD_LIBRARY_PATH:+$LD_LIBRARY_PATH:}/<userhome>/usr/lib/
-mkdir /<userhome>/usr/include/gtnets
-cp -fr SRC/*.h /<userhome>/usr/include/gtnets
+export LD_LIBRARY_PATH=${LD_LIBRARY_PATH:+$LD_LIBRARY_PATH:}/opt/gtnets/lib/
\endverbatim
+\subsection pls_simgrid_configuration_gtnets_config Enabling SimGrid's support for GTNetS
- - <b>Enable GTNetS support in SimGrid</b>
-
-In order to enable gtnets with simgrid you have to give where is gtnets. (path to \<gtnets_path\>/lib and \<gtnets_path\>/include)
+You just have to enable GTNetS in ccmake or cmake as follows, and
+recompile SimGrid.
\verbatim
-cmake . -Denable_gtnets=ON -Dgtnets_path=/<userhome>/usr
+cmake . -Denable_gtnets=ON -Dgtnets_path=/opt/gtnets
\endverbatim
- - <b>Once you have followed all the instructions for compiling and
- installing successfully you can activate this feature at
- runntime with the following options:</b>
+By the end of the configuration, cmake reports whether GTNetS was found.
+You can also double-check by executing the tests after the compilation.
\verbatim
-cd simgrid
-make
-ctest -R gtnets
+$ ctest -R gtnets
+(several tests should be run)
\endverbatim
+\subsection pls_simgrid_configuration_gtnets_use Using GTNetS from SimGrid
- - <b>Or try the GTNetS model dogbone example with</b>
+A working example can be found in the folder examples/msg/gtnets.
\verbatim
-gtnets/gtnets gtnets/onelink-p.xml gtnets/onelink-d.xml --cfg=network_model:GTNets
+gtnets/gtnets gtnets/onelink-p.xml gtnets/onelink-d.xml --cfg=network/model:GTNets
\endverbatim
+For more information, please refer to the <a
+href="http://www.ece.gatech.edu/research/labs/MANIACS/GTNetS/index.html">GTNetS
+Website</a> or to this
+<a href="http://gforge.inria.fr/docman/view.php/12/6283/GTNetS
+HowTo.html">possibly outdated longer HowTo</a>
- A long version of this <a href="http://gforge.inria.fr/docman/view.php/12/6283/GTNetS HowTo.html">HowTo</a> it is available
+\section pls_simgrid_configuration_ns3 NS3 as a SimGrid model
+You may want to replace the SimGrid network models by the ones of the
+well known packet-level network simulator <a href="http://www.nsnam.org/">NS-3</a> instead.
+This section explains how to do so.
- More about GTNetS simulator at <a href="http://www.ece.gatech.edu/research/labs/MANIACS/GTNetS/index.html">GTNetS Website</a>
-
-
- - <b>DISCLAIMER</b>
- The patches provided by us worked successfully with GTNetS found
- <a href="http://www.ece.gatech.edu/research/labs/MANIACS/GTNetS/software/gtnets-current.zip">here</a>,
- dated from 12th June 2008. Due to the discontinuing development of
- GTNetS it is impossible to precise a version number. We STRONGLY recommend you
- to download and install the GTNetS version found in SimGrid repository as explained above.
-
-\section pls_simgrid_configuration_ns3 Using NS3
-
-It is possible to use discrete-event network simulator <a href="http://www.nsnam.org/">(ns-3)</a> for Internet systems
-instead of the default one.
-
-A ns-3 platform is created according to the platform file you provide in SimGrid format. However from this configuration, we had to set up some extra parameters :
-
-<ul>
-<li>
-First, whenever possible, we let default ns3 values and we don't changed it ; in case you have doubts on values for those parameters (TCP parameters for example), blame ns-3...
-</li>
+\subsection pls_simgrid_configuration_ns3_install Installing NS3
-<li>
-Second, routing used inside ns-3 is a global and static one, relying on a shortest path algorithm. We did so by using ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables.
-</li>
-
-<li>
-Third, we also choose to restrict the way your platform is built : end hosts cannot have more than one interface card (so, only one <link> in your SimGrid platform should link
-an end host to the platform ; if not, your end host will be considered as a router.
-</li>
-
-</ul>
-<i>
-To use ns3 model inside SimGrid you have to install at least the version 3.10 of ns3 simulator.
-</i>
-
-- <b>Download and enter the lateast release (here the 3.12.1)</b>
+The easiest is to install it with the package manager. Under
+Debian/Ubuntu, simply type as root:
\verbatim
-http://www.nsnam.org/release/ns-allinone-3.12.1.tar.bz2
-tar -xf ns-allinone-3.12.1.tar.bz2
-cd ns-allinone-3.12.1/ns-3.12.1/
+apt-get install libns3-dev ns3
\endverbatim
-- <b>Configure, make and install ns3</b>
+You can also install it from scratch with the following commands:
\verbatim
+# Download the source
+wget http://www.nsnam.org/release/ns-allinone-3.22.tar.bz2
+tar -xf ns-allinone-3.22.tar.bz2
+cd ns-allinone-3.22/ns-3.22/
+# Configure, build and install
./waf configure --prefix="ns-3_install_directory"
./waf
./waf install
\endverbatim
-After install ns-3 you should have directories into your "ns-3_install_directory":
- \li include/ns3/
- \li lib/
- \li bin/ (with 3.12)
-
-In some cases, include/ns3 does not exist, but there is an /include/ns3.XX . Then, a simple symbolic link is enough. From the /path/to/ns3/installation/include directory, run:
-\verbatim
-ln -s -T ns3.XX/ns3 ns3
-\endverbatim
-
-Make sure to replace 3.XX with your version of NS3, e.g., 3.17, or 3.18.
-Check the correct presence of the symbolic link using
-\verbatim
-ls -al
-\endverbatim
-
-and you should see an ns3 link pointing to ns3.XX. E.g., ns3 -> ns3.17/ns3
-You also need to add to the LD_LIBRARY_PATH : "ns-3_install_directory/lib".
+For more information, please refer to the NS-3 documentation.
-- <b>Enable ns-3 support on SimGrid</b>
+\subsection pls_simgrid_configuration_ns3_config Enabling SimGrid's support for NS3
-Enabling ns-3 integration with Simgrid requires several intermediate steps.
--# Modify "simgrid_path/buildtools/CMake/MakeLib.cmake".\n
-The "-lns3.${NS3_VERSION_MINOR}-[module]" should match the library names in your "ns-3_install_directory/lib". The "module" can be one of the following: core, csma, point-to-oint, internet, applications, bridge, mpi, config-store, stats, network. For this, in the "MakeLib.cmake" file find the "else" branch of "if(HAVE_NS3)" statement. Replace the se of "-lns3.${NS3_VERSION_MINOR}-[module]" with "-lns3[version]-[module]-debug" in "SET(SIMGRID_DEP)". On the same branch, add "-I/path/to/ns-3_install_directory/include" to MAKE_C_FLAGS and "CMAKE_CXX_FLAGS".
--# There might be a need for creating symbolic links of each ns3 library from "ns-3_install_directory/lib" to "/usr/lib".
--# In order to enable ns-3 with simgrid you have to give where is ns-3 to the simgrid configuration command. (path to \<ns3_path\>/lib and \<ns3_path\>/include)
+Normally, you just have to enable NS3 in ccmake or cmake as follows.
+If you installed NS3 in a regular path, just drop the ns3_path
+configuration item.
\verbatim
cmake . -Denable_ns3=ON -Dns3_path=<ns3_path>
\endverbatim
-With the output of the configuration you can see if ns-3 is detected (see CFlags: ; CPPFlags: ; Compile NS-3: , NS-3 path:).
+By the end of the configuration, cmake reports whether NS-3 was found.
+You can also double-check by executing the tests after the compilation.
\verbatim
-Configuration of package `simgrid' on arch (=4):
- BUILDNAME : UNIX
- SITE : Linux_2.6.38-11-generic_x86_64
- Release : simgrid-3.6.1
-
- Compiler: c++ : /usr/bin/c++
- version: 4.6.1
- Compiler: c : /usr/bin/gcc
- version: 4.6.1
-
- CFlags : -O3 -finline-functions -funroll-loops -fno-strict-aliasing -L/usr/lib/x86_64-linux-gnu -I/usr/include
- -L/home/navarrop/Install/ns3-3.10/lib -I/home/navarrop/Install/ns3-3.10/include -g3 -D_NS3_3_10
- CPPFlags: -I/home/navarrop/Install/ns3-3.10/include -L/home/navarrop/Install/ns3-3.10/lib
-
- Compile Gtnets : 0
- Compile NS-3 : 1 ---------------------> Be sure this option is "1" otherwise ns-3 is not activated
- Gtnets path :
- NS-3 path : /home/navarrop/Install/ns3-3.10
- Compile Lua :
- Compile Smpi : OFF
- Compile Static : OFF
-
- Maintainer mode: OFF
- Supernovae mode: OFF
- Model checking : OFF
- Tracing mode : OFF
- Jedule mode : OFF
- Latency bound : OFF
- Graphviz mode :
-
- Simgrid dependencies: -lm -lpthread -lns3 -lrt
- Smpi dependencies :
-
- INSTALL_PREFIX: /usr/local
--- Configuring done
--- Generating done
--- Build files have been written to: /home/navarrop/workspace/simgrid/build
+$ ctest -R ns3
+(several tests should be run)
\endverbatim
-Now you can compile SimGrid
-\verbatim
-make
-\endverbatim
+If you have a NS3 version that is not known (yet) to SimGrid, the
+detection may fail. In that case, edit the file
+buildtools/Cmake/Modules/FindNS3.cmake in your SimGrid tree. The
+required changes are very easy, and documented at the beginning of
+this file.
-Then you can see if ns-3 is well activated by testing
-\verbatim
-ctest -R ns3
-\endverbatim
+If the compilation fails when linking the library because of some .a
+file that cannot be used dynamically, that's probably because you only
+installed the libns3-dev library on your Debian, where you also need
+libns3-3. That's probably a bug of the libns3-dev package that should
+depend on the dynamic libraries corresponding to its .so files.
-You should see
-\verbatim
- Start 182: msg-ns3-thread
-1/3 Test #182: msg-ns3-thread ................... Passed 0.35 sec
- Start 183: msg-ns3-ucontext
-2/3 Test #183: msg-ns3-ucontext ................. Passed 0.22 sec
- Start 184: msg-ns3-raw
-3/3 Test #184: msg-ns3-raw ...................... Passed 0.23 sec
-\endverbatim
+\subsection pls_simgrid_configuration_ns3_use Using NS3 from SimGrid
-- <b>Use case</b>
+A working example of NS3/SimGrid interactions can be found in
+examples/msg/ns3. Basically, you just have to run your SimGrid
+simulation with the configuration option "network/model" set to the
+value "NS3". The rest remains unchanged.
-An example of using Simgrid with NS3 can be found in:
+The following should work from the examples/msg/ns3 folder (ns3 here
+is the name of our example binary).
\verbatim
-path/to/simgrid/examples/src/surf/ns3/
+./ns3 ./3hosts_2links_p.xml 3hosts_2links_d.xml --cfg=network/model:NS3 --log=root.threshold:info
\endverbatim
-From the example folder above, the command line sintax is
+A ns-3 platform is automatically created from the SimGrid platform
+file that you will provide. There is some caveats to know:
-\verbatim
-<simgrid_executable> <platform description file> <deployment file> --cfg=network/model:NS3 --log=surf.threshold:info
-\endverbatim
+<ul>
+ <li>The default values (e.g., TCP parameters) are the ns3
+ values. Don't blame us for them.</li>
+
+ <li>NS3 networks are routed using the shortest path algorithm, using
+ ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables.</li>
+
+ <li>End hosts cannot have more than one interface card (so, only one
+ <link> in your SimGrid platform should link an end host to
+ the platform ; if not, your end host will be considered as a
+ router. </li>
+</ul>
-This example should work:
-\verbatim
-./ns3 ./3hosts_2links_p.xml 3hosts_2links_d.xml --cfg=network/model:NS3 --log=root.threshold:info
-\endverbatim
More about ns-3 simulator <a href="http://www.nsnam.org/">(Official website)</a>
