In this tutorial we will execute three examples demonstrating the GUI, the XML interface, and the Java interface.
The files for this tutorial are located at http://www.cs.cmu.edu/~haowen/15496/Recitation01/code.
Download them separately or grab the lot at
http://www.cs.cmu.edu/~haowen/15496/Recitation01/recitation1code.taz
or
http://www.cs.cmu.edu/~haowen/15496/Recitation01/recitation1code.rar
Before starting the tutorial, make sure to log in to CMULab here.
Also, be sure to quickly read over the emulator documentation: http://www.cs.cmu.edu/~emulator/doc/
This way you will know where to locate additional information if you require it.
Before any experiments can be run on the emulator, we must first define what nodes we need, what we want to name them, and which IP addresses shall we assign to them. We do this in an NS script file. The example in the recitation is 2node.ns. Read it carefully.
In the script file notice we have two nodes, called nodew1 and nodew2, defined in lines looking like:
set nodew1 [$ns node]
At the end of the file, we can select the IP for the wireless interface of each node, e.g.:
tb-set-ip-lan $nodew1 $lan0 10.1.1.1
The remainder of the settings are mostly self-explanatory; essentially to add a node to the topology we can just copy the lines that include nodew1. A comprehensive documentation of the meaning of all the tb commands can be found here (under My Emulab, Information -> Documentation -> Emulab-specific NS extensions Reference Manual). Also check the wireless settings here: https://boss.cmcl.cs.cmu.edu/tutorial/docwrapper.php3?docname=wireless.html#LinkConfig
Now that we have our NS script file ready, we are ready to start an experiment. On the CMULab website, go to Experimentation -> Begin Experiment. You will see a page like this:
The fields are quite self-explanatory. The experiment name should be short and unique since you'll be typing it a lot. I tend to use my username ("haowen") followed by a number. The description tells us what you're working on, e.g. assignment 1, project, etc. The NS file is uploaded with the browse function; if you made changes to it you can check its syntax with the "Check Syntax" button. Idle-Swap should be set to 1 hour because your experiment should never be idle. Max duration is not important as long as you Terminate the experiment as soon as you are done with it. The linktest option should be skipped since it is not relevant for our wireless experiments. The last two checkboxes should be left unchecked. Now hit "Submit" and you will see another screen with a log of the steps taken to set up the experiment (e.g. OS loaded on the nodes, rebooting, etc). Once the whole process is done (may take up to 10 minutes depending on number of nodes), you will receive an email and a popup window indicating that you've now got an active experiment:
Now you can look at your experiment details at My Emulab -> Experiments -> experiment name. Note the commands on the left, the most important ones are "Swap Out Experiment" and "Terminate Experiment". More on this later.
Now you want to login to your emucontrol-1 and your experiment nodes. Since we have two nodes, I would prefer to have three xterm windows open (1 window for each node and one for emucontrol-1):
I'm logged into emucontrol-1 on the left window; on the right windows I've performed an SSH to ops, then another ssh to the experiment node. Note that I can't get to the nodes unless I go through ops. Also note the naming convention: <node name>.<experiment name>.emulator.cmcl.cs.cmu.edu.
Once you are logged into the nodes if you type ifconfig ath0 you should see that each node has been assigned the IP address that you selected in your NS script file.
On emucontrol-1, we need to take one further step to setup a file needed to tell the emulator software the identity and addresses of the nodes in our experiment. Type:
emulatorDaemon <user ID> <project ID> <experiment ID>
For example, I will type:
emulatorDaemon haowen emulator haowen01
You'll get a few lines of script messages, and a file emulab.txt will be created in your home directory.
The file just contains some details about the nodes in your experiment: their user name; the machine name; the wireless IP address; the wired MAC address; and the node's wired IP. All this info can be safely ignored by you, you won't need it for the experiment.
If you need to stop your session for any reason, perform a swap out. Log out of your nodes and stop any emuRun processes. On the experiment profile on the My CMULab web interface, click on "Swap Out Experiment" and wait for the process to complete; you will receive an email when done. Now type again:
emulatorDaemon <user ID> <project ID> <experiment ID>
This will ensure that any subsequent executions of emuRun by you will not accidentally start messing up the signal environment of the nodes you have swapped out of.
When you're ready to resume the experiment, you may return to the control panel and click "swap in". Note that "swapping in" means a clean run of the same experiment; no state is saved by the swap out/in cycle.
After swapping out, if you're done with this configuration and don't need it any more, you can throw away the experiment by clicking "terminate experiment".
Note: Once the experiment is started, the nodes are allocated to you. If you need to take a break, ALWAYS swap out, stop any emuRun processes that are running, and run emulatorDaemon one more time to ensure that next time you don't accidentally run emuRun and destroy someone else's signal environment. Don't just leave your station: this will keep the nodes allocated to you and other students won't be able to run experiments on those nodes.
Now we're ready to run some experiments. On emucontrol-1, start emuRun with the guidemo.xml example:
emuRun guidemo.xml
Notice that at the end of the messages there is a message with a URL in it.
Open that URL up in your favourite JVM-equipped browser. You will be prompted for your reservation/GUI password which should have been given to you earlier via email from the TA. Then the GUI will open up:
Controls are pretty self-explanatory; details are here: http://www.cs.cmu.edu/~emulator/doc/GUI/GUI.html
Warning: Currently it seems to take some time (~5 mins) after the experiment session is first started before the channel signals actually get through. So always start up with a known good configuration file and keep sending pings from one node to another until something gets through; then you know the emulator is "warmed up" and ready for work. this is only true for the first execution of emuRun. Subsequent runs of emuRun should just work immediately.
Try putting the nodes at different distances from each other and measuring the data rate between each other.
You can do this with iperf. The documentation for iperf can be found on that site.
Here is an example screenshot. Recall that nodew1 was defined in the NS file to have IP 10.1.1.1 and nodew2 has an IP of 10.1.1.2.
This experiment shows that the data rate from nodew2 to nodew1 is 137Kbps.
When you're done, CTRL-C to break out of the emuRun process on emucontrol-1.
To see how the GUI shows mobility, you can do emuRun simpleRoute2.xml. Watch the nodes move around.
Now let's try running another example with a different XML config file. CTRL-C to break out of the emuRun process on emucontrol-1. Now look at the file xmldemo.xml. Notice the additional lines that say:
<EventGroup time="60" concurrent="true">
<Message>
<message>Moving node 2 to 90m away.</message>
</Message>
<SetPos>
<node>nodew2</node>
<pos>-90 0 0</pos>
</SetPos>
</EventGroup>
This means that at time 60s after the start of the experiment, node 2 will be moved immediately (teleported) to the new position (-90,0,0). Run this XML file:
emuRun xmldemo.xml
The teleport should be reflected in the GUI (you should see the node move to the new location). Take an iperf data rate reading before the teleport, and then another one after the teleport. You should be able to observe the change in data rates due to the increased attenuation at the farther distance.
For more information on how the XML files can define your wireless experiment parameters, refer to the emulator documentation here: http://www.cs.cmu.edu/~emulator/doc/scripts/Scripts.html
Another way to interface with the emulator is through the java interface. CTRL-C out of the previous emuRun and take a look at javademo.xml. Note the additional lines:
<UserClassDef>
<class>
<name>javaexample</name>
<args></args>
<url>http://localhost/</url>
</class>
</UserClassDef>
This means "load the class javaexample". This class is defined in the file javaexample.java. Read through it and try to understand each line: this java code does exactly the same thing as the previous XML-based example. The important thing to note here is that the class extends SimpleUserClass, and it is invoked at the start method when loaded by the emulator.
Now we need to compile the java file:
javac javaexample.java
This generates the file javaexample.class in java bytecode. We are now ready to run the emulator with this class:
emuRun javademo.xml
This will do exactly the same as the xmldemo: the node will teleport after 1 minute. Try repeating the same measurements to see how the data rate is affected. Feel free to play around with the code to see what else you can do.
For an exhaustive list of all classes and methods, consult the javadoc here:
http://www.cs.cmu.edu/~emulator/doc/api/index.html
Usually if a method is needed in an assignment, I will provide its description as a hint. However you may need other functionality in you projects so it is a good idea to familiarise yourself with the general java class structure of the emulator. Pay particular attention to SimpleUserClass because that will be the class you are inheriting: the member objects are how you will interact with the other pieces of the emulator.
Finishing up: When you're done with your tests, ALWAYS remember to terminate your experiment. On the Emulab website, Go to: My Emulab -> experiments -> select your experiment and terminate it from the commands options on the left sidebar.
Congratulations! You have completed the tutorial. You should now be able to (very easily) complete assignment 1, which is not much more than this.