X-Git-Url: http://bilbo.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/62af461109d7cffb84a3d5d017c4740c9cbe0802..f5b39e2dbef339ffb889350f4b6376b2b871b208:/docs/source/ns3.rst diff --git a/docs/source/ns3.rst b/docs/source/ns3.rst index 5e3cb563aa..a4b39fb5d0 100644 --- a/docs/source/ns3.rst +++ b/docs/source/ns3.rst @@ -3,42 +3,38 @@ 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 - - apt-get install libns3-dev ns3 +The SimGrid/ns-3 binding only contains features that are common to both systems. +Not all ns-3 models are available from SimGrid (only the TCP and WiFi ones are), +while not all SimGrid platform files can be used in conjunction ns-3 (routes +must be of length 1). Also, the platform built in ns-3 from the SimGrid +description is very basic. Finally, communicating from a host to +itself is forbidden in ns-3, so every such communication completes +immediately upon startup. -You can also install it from scratch with the following commands: -.. code-block:: shell +Compiling the ns-3/SimGrid binding +********************************** - # 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/ - # Configure, build and install - ./waf configure --prefix="/opt/ns3" # or give another path if you prefer - ./waf - ./waf install +Installing ns-3 +=============== -For more information, please refer to the ns-3 documentation -(`official website `_). +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 (see the `ns-3 documentation `_). -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 tell cmake where ns3 is installed on +your disk. .. code-block:: shell @@ -47,130 +43,241 @@ 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 that ns-3 was successfully integrated with the following (from your SimGrid +build directory). It will run all SimGrid tests that are related to the ns-3 +integration. If no test is run at all, you probably forgot to enable ns-3 in cmake. .. 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 -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 -example of invalid platform: +example of an invalid platform: -.. code-block:: shell +.. code-block:: xml - - - + + + + + + - - - - - - - + + + + + + + + -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 (using +``ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables``). -.. code-block:: shell +.. code-block:: xml - - - + + + + + + - + - - + + - - - + + + - - - + + + + Once your platform is OK, just change the :ref:`network/model -` configuration option to "NS3" as follows. The rest -is unchanged. +` configuration option to `ns-3` as follows. The other +options can be used as usual. .. 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 +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 `_ +Check the file `examples/s4u/network-ns3/network-ns3.tesh `_ to see which ones are used in our regression tests. -Shortcomings of the ns-3 bindings in SimGrid --------------------------------------------- +WiFi platforms +-------------- -A ns-3 platform is automatically created from the provided SimGrid -platform. However, there are some known caveats: +In SimGrid, WiFi networks are modeled with WiFi zones, where a zone contains +the access point of the WiFi network and the hosts connected to it (called +station in the WiFi world). Links inside WiFi zones are modeled as regular +links with a specific attribute, and these links are then added to routes +between hosts. The main difference When using ns-3 WiFi networks is that +the network performance is not given by the link bandwidth and latency but +by the access point WiFi characteristics, and the distance between the access +point and the hosts. + +So, to declare a new WiFi network, simply declare a zone with the ``WIFI`` +routing. + +.. code-block:: xml + + + +Inside this zone you must declare which host or router will be the access point +of the WiFi network. + +.. code-block:: xml + + - * The default values (e.g., TCP parameters) are the ns3 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 - SimGrid hosts should be connected to the platform through only - one link. Otherwise, your SimGrid host will be considered as a - router. +Afterward simply declare the hosts and routers inside the WiFi network. Remember +that one must have the same name as declared in the property "access point". -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. +.. code-block:: xml -Troubleshooting with ns-3 and SimGrid -************************************* + + + -I fail to compile ns-3 within SimGrid -------------------------------------- +Finally, close the WiFi zone. -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. +.. code-block:: xml -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 ----------------------------------- +The WiFi zone may be connected to another zone using a traditional link and +a zoneRoute. Note that the connection between two zones is always wired. -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. +.. code-block:: xml -Arguably, SimGrid could detect this situation and report it, but -unfortunately, this is still to be done. + -I get a warning that some routes are ignored --------------------------------------------- + + + + +WiFi network performance +^^^^^^^^^^^^^^^^^^^^^^^^ + + +The performance of a wifi network is controlled by 3 property that can be added +to hosts connected to the wifi zone: + + * ``mcs`` (`Modulation and Coding Scheme `_) + Roughly speaking, it defines the speed at which the access point is + exchanging data with all stations. It depends on its model and configuration, + and the possible values are listed for example on Wikipedia. + |br| By default, ``mcs=3``. + It is a property of the WiFi zone. + * ``nss`` (Number of Spatial Streams, or `number of antennas `_) + defines the amount of simultaneous data streams that the AP can sustain. + Not all value of MCS and NSS are valid nor compatible (cf. `802.11n standard `_). + |br| By default, ``nss=1``. + It is a property of the WiFi zone. + * ``wifi_distance`` is the distance from the station to the access point. Each + station can have a specific value. + |br| By default, ``wifi_distance=10``. + It is a property of stations of the WiFi network. + +Here is an example of a zone changing ``mcs`` and ``nss`` values. + +.. code-block:: xml + + + + + + ... + + +Here is an example of a host changing ``wifi_distance`` value. + +.. code-block:: xml + + + + + +Random Number Generator +======================= + +It is possible to define a fixed or random seed to the ns3 random number +generator using the config tag. + +.. code-block:: xml + + + + + + + + ... + + +The first property defines that this platform will be used with the ns3 model. +The second property defines the seed that will be used. Defined to ``time`` +it will use a random seed, defined to a number it will use this number as +the seed. + +Limitations +=========== + +A ns-3 platform is automatically created from the provided SimGrid +platform. However, there are some known caveats: -Any routes longer than one hop are ignored in ns-3. Please refer to -:ref:`ns3_use` for details. + * 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 SimGrid hosts + should be connected to the platform through only one link. Otherwise, your + SimGrid host will be considered as a router (FIXME: is it still true?). + +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. + +Troubleshooting +=============== + +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. + +.. |br| raw:: html + +