X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/62af461109d7cffb84a3d5d017c4740c9cbe0802..8f60290eae05609bcb837401cd66af627b39370a:/docs/source/ns3.rst diff --git a/docs/source/ns3.rst b/docs/source/ns3.rst index 5e3cb563aa..c4e27ea7a7 100644 --- a/docs/source/ns3.rst +++ b/docs/source/ns3.rst @@ -3,28 +3,29 @@ ns-3 as a SimGrid model ####################### -You can use the well-known `ns-3 `_ packet-level network -simulator as a SimGrid model, for example to investigate the validity of your -simulation. Just install ns-3 and recompile SimGrid accordingly. +You can use the well-known `ns-3 packet-level network simulator +`_ as a SimGrid model, for example to investigate the +validity of your simulation. Just install ns-3 and recompile SimGrid +accordingly. -Installing ns-3 -*************** - -The easiest is to install it with the package manager. Under Debian/Ubuntu, -simply type as root: - -.. code-block:: shell +Compiling the ns-3/SimGrid binding +********************************** - apt-get install libns3-dev ns3 +Installing ns-3 +=============== -You can also install it from scratch with the following commands: +SimGrid requires ns-3 version 3.26 or higher, and you probably want the most +recent version of both SimGrid and ns-3. While the Debian package of SimGrid +don't have the ns-3 bindings activated, you can still use the packaged version +of ns-3 by grabbing the ``libns3-dev ns3`` packages. Alternatively, you can +install ns-3 from scratch as follows: .. code-block:: shell # Download the source - wget http://www.nsnam.org/release/ns-allinone-3.26.tar.bz2 - tar -xf ns-allinone-3.26.tar.bz2 - cd ns-allinone-3.26/ns-3.26/ + wget http://www.nsnam.org/release/ns-allinone-3.29.tar.bz2 + tar -xf ns-allinone-3.29.tar.bz2 + cd ns-allinone-3.29/ns-3.29/ # Configure, build and install ./waf configure --prefix="/opt/ns3" # or give another path if you prefer ./waf @@ -33,12 +34,11 @@ You can also install it from scratch with the following commands: For more information, please refer to the ns-3 documentation (`official website `_). -Enabling SimGrid's support for ns-3 -*********************************** +Enabling ns-3 in SimGrid +======================== -Normally, you just have to enable ns-3 in ccmake or cmake as -follows. If you installed ns-3 in a regular path, just drop the -NS3_HINT configuration item. +SimGrid must be recompiled with the ``enable_ns3`` option activated in cmake. +Optionally, use ``NS3_HINT`` to hint cmake about where to find ns-3. .. code-block:: shell @@ -47,26 +47,36 @@ NS3_HINT configuration item. By the end of the configuration, cmake reports whether ns-3 was found, and this information is also available in ``include/simgrid/config.h`` If your local copy defines the variable ``SIMGRID_HAVE_NS3`` to 1, then ns-3 -was correctly detected. If it's defined to 0, then something went -wrong. Explore ``CMakeFiles/CMakeOutput.log`` and +was correctly detected. Otherwise, explore ``CMakeFiles/CMakeOutput.log`` and ``CMakeFiles/CMakeError.log`` to diagnose the problem. -Afterward, you can test your installation as follows: +Test your installation after compilation as follows: .. code-block:: shell ctest -R ns3 +Troubleshooting +=============== + +If you use a version of ns-3 that is not known to SimGrid yet, edit +``tools/cmake/Modules/FindNS3.cmake`` in your SimGrid tree, according to the +comments on top of this file. Conversely, if something goes wrong with an old +version of either SimGrid or ns-3, try upgrading everything. + .. _ns3_use: Using ns-3 from SimGrid *********************** -The SimGrid-ns3 binding only contains features that are common to both +The SimGrid/ns-3 binding only contains features that are common to both systems: ns-3 wireless models are not available, while SimGrid routes cannot be longer than 1. Also, the platform built in ns-3 from the SimGrid description is very basic. +Platform files compatibility +============================ + Any route longer than one will be ignored when using ns-3. They are harmless, but you still need to connect your hosts using one-hop routes. The best solution is to add routers to split your route. Here is an @@ -82,14 +92,14 @@ example of invalid platform: - - + + -Here is the same platform expressed in a way that ns-3 will understand. -There is no direct connexion from alice to bob, but that's OK because -ns-3 will find the path from point to point. +This can be reformulated as follows to make it usable with the ns-3 binding. +There is no direct connection from alice to bob, but that's OK because +ns-3 automatically routes from point to point. .. code-block:: shell @@ -112,25 +122,25 @@ ns-3 will find the path from point to point. Once your platform is OK, just change the :ref:`network/model -` configuration option to "NS3" as follows. The rest +` configuration option to "ns-3" as follows. The rest is unchanged. .. code-block:: shell - ./network-ns3 --cfg=network/model:NS3 (other parameters) + ./network-ns3 --cfg=network/model:ns-3 (other parameters) Many other files from the ``examples/platform directory`` are usable with the ns-3 model, such as `examples/platforms/dogbone.xml `_. Check the file `examples/deprecated/msg/network-ns3/network-ns3.tesh `_ to see which ones are used in our regression tests. -Shortcomings of the ns-3 bindings in SimGrid --------------------------------------------- +Limitations +=========== A ns-3 platform is automatically created from the provided SimGrid platform. However, there are some known caveats: - * The default values (e.g., TCP parameters) are the ns3 default values. + * The default values (e.g., TCP parameters) are the ns-3 default values. * ns-3 networks are routed using the shortest path algorithm, using ``ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables``. * End hosts cannot have more than one interface card. So, your @@ -138,39 +148,16 @@ platform. However, there are some known caveats: one link. Otherwise, your SimGrid host will be considered as a router. -Our goal is to keep the ns-3 plugin of SimGrid as easy (and hopefully -readable) as possible. If the current state does not fit your needs, -you should modify this plugin, and/or create your own plugin from the -existing one. - -Troubleshooting with ns-3 and SimGrid -************************************* - -I fail to compile ns-3 within SimGrid -------------------------------------- - -If you have a ns-3 version that is not known to SimGrid yet, edit -``tools/cmake/Modules/FindNS3.cmake`` in your SimGrid tree, according to -the comments on top of this file. - -If the compilation fails on Debian/Ubuntu when linking the library -because of some .a file that cannot be used dynamically, then you are -probably using a very old (and buggy) ``libns3-dev`` -package. Update it, or install ``libns3-3`` manually. - -The simulation hangs at some point ----------------------------------- - -If your simulation hangs in a communication, this is probably because -one host is sending data that is not routable in your platform. Make -sure that you only use routes of length 1, and that any host is -connected to the platform. - -Arguably, SimGrid could detect this situation and report it, but -unfortunately, this is still to be done. +Our goal is to keep the ns-3 plugin of SimGrid as easy (and hopefully readable) +as possible. If the current state does not fit your needs, you should modify +this plugin, and/or create your own plugin from the existing one. If you come up +with interesting improvements, please contribute them back -I get a warning that some routes are ignored --------------------------------------------- +Troubleshooting +=============== -Any routes longer than one hop are ignored in ns-3. Please refer to -:ref:`ns3_use` for details. +If your simulation hangs in a communication, this is probably because one host +is sending data that is not routable in your platform. Make sure that you only +use routes of length 1, and that any host is connected to the platform. +Arguably, SimGrid could detect this situation and report it, but unfortunately, +this is still to be done.