Before start you must verify these points:
In order to install DCE you must follow the tutorial part “Building ns-3 and DCE”.
The result of the installation process is the creation of libraries from source of DCE and that of NS-3 and also some tools and sources of an optional Linux kernel if you have also chosen to use the stack of a linux kernel. Below you will find the main directories:
├── build Target of NS-3 Core and DCE compilation
│ ├── bin
│ ├── include
│ └── lib
│
├── ns-3-dce DCE main tree
│ ├── build Target of DCE compilation
│ │ ├── bin
│ │ ├── bin_dce
│ │ ├── lib
│ ├── doc Documentation source
│ ├── example Some exemple of scenarios using DCE
│ │ ├── bash
│ │ └── ccnx
│ ├── helper Source code of DCE
│ ├── model Source code of DCE
│ ├── netlink Source code of DCE
│ ├── ns3waf
│ ├── test Source code of DCE unit tests
│ └── utils Utility scripts for DCE build and use
│
├── ns-3-dev NS-3 CORE Main tree
│ ├── bindings NS-3 Core python bindings
│ ├── build Target of NS-3 Core compilation
│ ├── doc Documentation source
│ ├── examples Many exemple of scenarios using NS-3
│ ├── ns3 empty directory
│ ├── scratch Scratch directory usable to write scripts
│ ├── src NS-3 source code
│ ├── utils Utilities
│ └── waf-tools "Makefile" tool like
│
└── readversiondef Little utility used by DCE to create dynamic libraries version tags. Used only during compilation of DCE.
In order to use DCE you should configure some environments variables, some of them are the standards paths where to find executables and dynamic libraries, other are DCE specifics. The following script do the job for you: ns-3-dce/utils/setenv.sh, so you should call this script prior to use DCE.
The DCE specifics variables are essentially two PATH like variables: so within them you may put paths separated by ‘:’ character.
DCE_PATH is used by DCE to find the executable you want to launch within NS-3 simulated network. This variable is used when you reference the executable using a relative form like ‘ping’.
DCE_ROOT is similar to DCE_PATH but it is used when you use an absolute form for exemple ‘/bin/bash’.
Please pay attention that executables that you will place in the directories indicated in the previous variables should be recompiled accordingly to the rules defined in the next chapter.
To start a program in the world of NS-3 you must indicate on which node it will be launched. Once launched this program will have access only to the file system corresponding to the node that corresponds to a directory on your machine called file-X where X is the decimal number of the corresponding node. The file-X directories are created by DCE, only when they do not already exist. Also note that the contents of this directory is not cleared when starting the script. So you can copy the files required for the operation of your executables in the tree nodes. If possible it is best that you create these files from the script itself in order to simplify maintenance. DCE provides some helpers for creating configuration files necessary to the execution of certain apps like CCNx and Quagga.
Your program running in a NS-3 node views the network defined by the script for this node.
Time perceived by your executable is the simulated time of NS-3. Also note that DCE supports real time scheduler of NS-3 with the same limitations.
As explained in Part How it works DCE needs to relocate the executable in memory, to do this it is necessary to recompile the exe target. In order to this you should follow the two following rules:
Copy the executable file produced in a specified directory in the variable environment DCE_PATH so that DCE can find it.
Now that you have compiled your executable you can use it within NS-3 script with the help of a set of DCE Helper Class:
| HELPER CLASS NAME | INCLUDE NAME | DESCRIPTION |
| DceManagerHelper | ns3/dce-manager-helper.h | A DceManager is a DCE internal class which manage the execution of the executable you will declare to run within NS-3; The DceManagerHelper is the tool you will use within your script to parameter and install DceManager on the NS-3 nodes where you plan to run binaries. |
| DceApplicationHelper | ns3/dce-application-helper.h | You will use this helper in order to define which application you want to run within NS-3 by setting the name of the binary its optionals arguments , its environment variables, and also optionaly if it take its input from a file instead of stdin. This class can be derived if you need to do more preparation before running your application. Often applications need configuration file to work properly, for example if you look at the contents of the helper named CcnClientHelper you will see that his job is to create the key files needed for the operation of CCNx’s applications. |
| CcnClientHelper | ns3/ccn-client-helper.h | This helper is a subclass of DceApplicationHelper, its jobs is to create keys files used by ccnx executables in order to run them correctly within NS3. |
| QuaggaHelper | ns3/quagga-helper.h | This helper is a subclass of DceApplicationHelper. It will help you to setup Quagga applications. |
Note that the table above indicates the name of includes, so you can look at the comments in them, but in reality for DCE use you need to include only the file ns3/dce-module.h.
The directory named myscripts is a good place to place your scripts. To create a new script you should create a new directory under myscripts, and put your sources and a configuration file for waf build system, this file should be named wscript. For starters, you may refer to the contents of the directory myscripts/ping.
To compile simply execute the command waf. The result must be under the directory named build/bin/myscripts/foo/bar where foo is your directory and bar your executable according to the content of your wscript file. note you should not forget to set environment variables using the setenv.sh script located in the utils directory.
Simply launch your script like any other program. If it does not work you may have forgotten to place the environment variables using the setenv.sh script located in the utils directory.
The execution of the apps using DCE generates special files which reflect the execution thereof. On each node DCE creates a directory /var/log, this directory will contain subdirectory whose name is a number. This number is the pid of a process. Each of these directories contains the following files cmdline, status, stdout, stderr. The file cmdline recalls the name of the executable run followed arguments. The file status contains an account of the execution and dating of the start; optionally if the execution is completed there is the date of the stop and the return code. The files stdout and stderr correspond to the standard output of the process in question.
It is possible to use gdb to debug a script DCE/NS-3. As explained somewhere in the execution of a script is monoprocess, then you can put breakpoints in both sources of DCE and those of binaries hosted by DCE.
If you use gdb (a CVS or stable version), do not forget to execute the following command prior to running any DCE-based program::
(gdb) handle SIGUSR1 nostop
Signal StopPrintPass to programDescription
SIGUSR1 NoYesYesUser defined signal 1
(gdb)
An alternate way to do this and avoid having to repeat this command ad-nauseam involves creating a .gdbinit file in your ns-3-dce directory and putting this inside::
handle SIGUSR1 nostop
DCE is configurable with NS3 Attributes. Refer to the following table:
| ATTRIBUTE NAME | DESCRIPTION | VALUES | EXAMPLES |
| FiberManagerType | The TaskManager is used to switch the execution context between threads and processes. | UcontextFiberManager the more efficient. PthreadFiberManager helpful with gdb to see the threads. This is the de fault. |
--ns3::TaskManager::FiberManagerType=UcontextFiberManager dceManager.SetTaskManagerAttribute("FiberManagerType", StringValue("UcontextFiberManager")); --ns3::TaskManager::FiberManagerType=PthreadFiberManager |
| LoaderFactory | The LoaderFactory is used to load the hosted binaries. | CoojaLoaderFactory is the default and the only one that supports fork. DlmLoaderFactory is the more efficient. To use it you have two ways:
2. link using ldso as default interpreter. |
--ns3::DceManagerHelper::LoaderFactory=ns3::CoojaLoaderFactory[] $ dce-runner my-dce-ns3-script OR gcc -o my-dce-ns3-script Wl,--dynamic-linker=PATH2LDSO/ldso ... $ my-dce-ns3-script --ns3::DceManagerHelper::LoaderFactory=ns3::Dl mLoaderFactory[] dceManager.SetLoader("ns3::DlmLoaderFactory"); |