Difference between revisions of "HOWTO use ns-3 directly on the ORBIT testbed hardware"
(→HOWTO use ns-3 directly on the ORBIT testbed hardware) |
|||
Line 20: | Line 20: | ||
We provide a node image on the ORBIT system that includes everything you need to | We provide a node image on the ORBIT system that includes everything you need to | ||
get an ns-3 environment up and running on your testbed nodes. This includes the | get an ns-3 environment up and running on your testbed nodes. This includes the | ||
− | GNU toolchain, a copy of a precompiled ns-3. | + | GNU toolchain, a copy of a precompiled fully-loaded ns-3.5 repository with NSC, |
− | first step is to get this environment up on the nodes in your | + | Python bindings, emacs editor, etc., as well as a couple of specialized scripts |
+ | to demonstrate a client-server (UDP Echo Client and Server) pair talking between | ||
+ | two sandbox nodes. | ||
+ | |||
+ | The first step is to get this environment up on the nodes in your sandbox. In ORBIT | ||
terminology, we need to "image the nodes." | terminology, we need to "image the nodes." | ||
− | 1. Connect to the sandbox console, image the sandbox nodes | + | 1. Connect to the sandbox console (we are assuming sandbox one, you need to substitute |
+ | the correct address) and image the sandbox nodes: | ||
+ | |||
a. ssh your-orbit-user-name@console.sb1.orbit-lab.org; | a. ssh your-orbit-user-name@console.sb1.orbit-lab.org; | ||
− | b. orbit load all ns-3. | + | b. orbit load all ns-3.5.ndz |
This is a somewhat time-consuming process since you are actually copying disk | This is a somewhat time-consuming process since you are actually copying disk | ||
− | images to the sandbox nodes. The example below took about | + | images to the sandbox nodes. The example below took about fifteen and a half |
− | minutes to complete | + | minutes to complete! You should see status messages appearing which indicate |
that the imaging process is proceeding as expected: | that the imaging process is proceeding as expected: | ||
− | + | Imaging nodes: 'system:topo:all' with image 'ns-3.5.ndz' | |
− | + | (Domain: default from hostname) | |
− | + | (Timeout: 800 sec.) | |
− | + | INFO init: NodeHandler Version 4.4.0 (1921) | |
− | + | INFO init: Experiment ID: sb1_2009_07_10_01_07_20 | |
− | + | INFO NodeHandler: Shutdown Flag Set - Switching all nodes Off... | |
− | + | INFO Experiment: load system:exp:stdlib | |
− | + | INFO prop.resetDelay: resetDelay = 210:Fixnum | |
− | + | INFO prop.resetTries: resetTries = 1:Fixnum | |
− | + | INFO Experiment: load system:exp:imageNode | |
− | + | INFO prop.nodes: nodes = "system:topo:all":String | |
− | + | INFO prop.image: image = "ns-3.5.ndz":String | |
− | + | INFO prop.domain: domain = nil:NilClass | |
− | + | INFO prop.timeout: timeout = 800:Fixnum | |
− | + | INFO Topology: Loading topology 'system:topo:all'. | |
− | + | INFO stdlib: Waiting for nodes (Up/Down/Total): 0/2/2 - (still down: n_1_1,n_1_2) | |
− | + | ||
− | + | ... | |
− | + | ||
− | + | INFO whenAll: *: 'status[@value='UP']' fires | |
− | + | INFO exp: Progress(0/0/2): 0/0/0 min(n_1_1)/avg/max (83) - Timeout: 709 sec. | |
− | + | INFO exp: Progress(0/0/2): 0/0/0 min(n_1_1)/avg/max (83) - Timeout: 699 sec. | |
− | + | INFO exp: Progress(0/0/2): 0/0/0 min(n_1_1)/avg/max (83) - Timeout: 689 sec. | |
− | + | ||
− | + | ... | |
− | + | ||
− | + | INFO exp: Progress(0/0/2): 90/90/90 min(n_1_1)/avg/max (83) - Timeout: 126 sec. | |
− | + | INFO exp: Progress(0/0/2): 90/90/90 min(n_1_1)/avg/max (83) - Timeout: 116 sec. | |
+ | INFO exp: Progress(1/0/2): 90/95/100 min(n_1_2)/avg/max (83) - Timeout: 106 sec. | ||
+ | INFO exp: Progress(2/0/2): 100/100/100 min()/avg/max (83) - Timeout: 96 sec. | ||
+ | INFO exp: ----------------------------- | ||
+ | INFO exp: Imaging Process Done | ||
+ | INFO exp: - 2 node(s) succesfully imaged - See the topology file: 'system_topo_active_sb1.rb' | ||
+ | INFO exp: ----------------------------- | ||
+ | INFO Experiment: DONE! | ||
+ | INFO ExecApp: Application 'commServer' finished | ||
+ | INFO run: Experiment sb1_2009_07_10_01_07_20 finished after 15:35 | ||
− | You can now take a look at the status of the nodes. Observe that they are in the | + | 2. You can now take a look at the status of the nodes. Observe that they are in the |
POWEROFF state | POWEROFF state | ||
− | + | a. orbit stat | |
− | + | ----------------------------------------------- | |
INFO Topology: Loading topology 'system:topo:all'. | INFO Topology: Loading topology 'system:topo:all'. | ||
Testbed : sb1 | Testbed : sb1 |
Revision as of 05:24, 10 July 2009
Main Page - Current Development - Developer FAQ - Tools - Related Projects - Project Ideas - Summer Projects
Installation - Troubleshooting - User FAQ - HOWTOs - Samples - Models - Education - Contributed Code - Papers
We provide a realtime emulation package that allows us to connect ns-3 to real networks on real machines. Typically the real network will be a testbed of some kind. ORBIT is a two-tier laboratory emulator/field trial network project of WINLAB (Wireless Information Network Laboratory), at Rutgers. This wireless network emulator provides a large two-dimensional grid of 400 802.11 radio nodes as well as a number of smaller "sandbox" testbeds to allow one to test without reserving the main grid. This HOWTO shows how ns-3 scripts can be used to drive these radio nodes.
We assume that you have some experience with the ORBIT system. If you are new to ORBIT, please take a look at http://www.orbit-lab.org/ and go through the "Basic Tutorial" and the "Tutorials on controlling the testbed nodes" at a minimum. We will assume throughout this HOWTO that you have registered for an ORBIT account and have made a reservation on the ORBIT Scheduler for a testbed. This HOWTO assumes that you are on the sandbox one (sb1) testbed.
HOWTO use ns-3 directly on the ORBIT testbed hardware
We provide a node image on the ORBIT system that includes everything you need to get an ns-3 environment up and running on your testbed nodes. This includes the GNU toolchain, a copy of a precompiled fully-loaded ns-3.5 repository with NSC, Python bindings, emacs editor, etc., as well as a couple of specialized scripts to demonstrate a client-server (UDP Echo Client and Server) pair talking between two sandbox nodes.
The first step is to get this environment up on the nodes in your sandbox. In ORBIT terminology, we need to "image the nodes."
1. Connect to the sandbox console (we are assuming sandbox one, you need to substitute the correct address) and image the sandbox nodes:
a. ssh your-orbit-user-name@console.sb1.orbit-lab.org; b. orbit load all ns-3.5.ndz
This is a somewhat time-consuming process since you are actually copying disk images to the sandbox nodes. The example below took about fifteen and a half minutes to complete! You should see status messages appearing which indicate that the imaging process is proceeding as expected:
Imaging nodes: 'system:topo:all' with image 'ns-3.5.ndz' (Domain: default from hostname) (Timeout: 800 sec.) INFO init: NodeHandler Version 4.4.0 (1921) INFO init: Experiment ID: sb1_2009_07_10_01_07_20 INFO NodeHandler: Shutdown Flag Set - Switching all nodes Off... INFO Experiment: load system:exp:stdlib INFO prop.resetDelay: resetDelay = 210:Fixnum INFO prop.resetTries: resetTries = 1:Fixnum INFO Experiment: load system:exp:imageNode INFO prop.nodes: nodes = "system:topo:all":String INFO prop.image: image = "ns-3.5.ndz":String INFO prop.domain: domain = nil:NilClass INFO prop.timeout: timeout = 800:Fixnum INFO Topology: Loading topology 'system:topo:all'. INFO stdlib: Waiting for nodes (Up/Down/Total): 0/2/2 - (still down: n_1_1,n_1_2) ...
INFO whenAll: *: 'status[@value='UP']' fires INFO exp: Progress(0/0/2): 0/0/0 min(n_1_1)/avg/max (83) - Timeout: 709 sec. INFO exp: Progress(0/0/2): 0/0/0 min(n_1_1)/avg/max (83) - Timeout: 699 sec. INFO exp: Progress(0/0/2): 0/0/0 min(n_1_1)/avg/max (83) - Timeout: 689 sec. ...
INFO exp: Progress(0/0/2): 90/90/90 min(n_1_1)/avg/max (83) - Timeout: 126 sec. INFO exp: Progress(0/0/2): 90/90/90 min(n_1_1)/avg/max (83) - Timeout: 116 sec. INFO exp: Progress(1/0/2): 90/95/100 min(n_1_2)/avg/max (83) - Timeout: 106 sec. INFO exp: Progress(2/0/2): 100/100/100 min()/avg/max (83) - Timeout: 96 sec. INFO exp: ----------------------------- INFO exp: Imaging Process Done INFO exp: - 2 node(s) succesfully imaged - See the topology file: 'system_topo_active_sb1.rb' INFO exp: ----------------------------- INFO Experiment: DONE! INFO ExecApp: Application 'commServer' finished INFO run: Experiment sb1_2009_07_10_01_07_20 finished after 15:35
2. You can now take a look at the status of the nodes. Observe that they are in the POWEROFF state
a. orbit stat
----------------------------------------------- INFO Topology: Loading topology 'system:topo:all'. Testbed : sb1 Node n_1_1 - State: POWEROFF Node n_1_2 - State: POWEROFF -----------------------------------------------
You can now power up the nodes in the sandbox
d. orbit tell on all
INFO Topology: Loading topology 'system:topo:all'. --------------------------------------------------- Testbed : sb1 - Command: on Node n_1_2 - Ok Node n_1_1 - Ok ---------------------------------------------------
and see that the nodes are now powered up
e. orbit stat
----------------------------------------------- INFO Topology: Loading topology 'system:topo:all'. Testbed : sb1 Node n_1_1 - State: POWERON Node n_1_2 - State: POWERON -----------------------------------------------
When you are done with this step, the sandbox nodes will have been powered up and will be in the process of booting. You now need to connect to the individual nodes in the sandbox and configure them. You may find it convenient to open a couple of terminal windows for this process. I will assume you do this, and in from now on, when I refer to [x,y] I mean the terminal window into which you you connect to the ORBIT node of array position [x,y].
You may see a "No route to host" error, when you try to ssh, until the nodes are actually up (done rebooting as a result of the power on step 1.d). Note that we configure "ath0" on node [1,1] to be an access point, and "ath0" on node [1,2] to be a station. We have to place the cards in promiscuous mode for the emu net device to work.
2. Connect to node [1,1] and configure its wireless
a. ssh root@node1-1 b. wlanconfig ath0 destroy c. wlanconfig ath0 create wlandev wifi0 wlanmode ap d. ifconfig ath0 promisc up
3. Connect to node [1,2] and configure its wireless
a. ssh root@node1-2 b. wlanconfig ath0 destroy c. wlanconfig ath0 create wlandev wifi0 wlanmode sta d. ifconfig ath0 promisc up
Now that you have a working hardware configuration, you can go ahead and get ns-3 up and running. The image you loaded is of a vanilla ns-3.3 distribution. In that distro there are no example programs handy which can drive the two nodes in the sandbox. We provide a couple of example progams on one of our developers' private repositories to get you started.
6. Pull the examples into [1,1] and build them
a. cd /home/repos/ns-3.3 b. hg pull http://code.nsnam.org/craigdo/ns-3.3-orbit c. hg update d. ./waf
7. Pull the examples into [1,2] and build them
a. cd /home/repos/ns-3.3 b. hg pull http://code.nsnam.org/craigdo/ns-3.3-orbit c. hg update d. ./waf
Now you can run the example ns-3 client server scripts on the testbed. We have configured [1,1] device "ath0" as an access point, and [1,2] device "ath0" as a station. Both devices must be in promiscuous mode. This can all be verified by using "ifconfig" and "iwconfig" on the appropriate console.
This is annoying, but for now we have got to manually set the hardware address of the interfaces in the ns-3 simulation script.
8. Set the hardware address of the interface in the server script on node [1,1]
a. ifconfig
Locate the output for the device ath0 in the output of ifconfig
ath0 Link encap:Ethernet HWaddr 06:60:b3:ac:2b:f5 inet6 addr: fe80::460:b3ff:feac:2bf5/64 Scope:Link UP BROADCAST RUNNING PROMISC MULTICAST MTU:1500 Metric:1 RX packets:1728 errors:0 dropped:0 overruns:0 frame:0 TX packets:42 errors:0 dropped:0 overruns:0 carrier:0 collisions:0 txqueuelen:0 RX bytes:1769806 (1.6 MiB) TX bytes:2216 (2.1 KiB)
Copy the HWaddr to the clipboard (in this case, 06:60:b3:ac:2b:f5)
b. cd examples c. emacs emu-udp-echo-server.cc # or use your favorite editor
Search for the MAC address assigmnet and replace the string with the HWaddr you just found, for example,
ed->SetAddress ("06:60:b3:ac:2b:f5");
Save the changes and build
d. ./waf
9. Set the hardware address of the interface in the client script on node [1,2]
a. ifconfig
Locate the output for the device ath0 in the output of ifconfig
ath0 Link encap:Ethernet HWaddr 06:60:b3:b0:c6:a4 inet6 addr: fe80::460:b3ff:feb0:c6a4/64 Scope:Link UP BROADCAST RUNNING PROMISC MULTICAST MTU:1500 Metric:1 RX packets:72 errors:0 dropped:0 overruns:0 frame:0 TX packets:851 errors:0 dropped:0 overruns:0 carrier:0 collisions:0 txqueuelen:0 RX bytes:1900 (1.8 KiB) TX bytes:890770 (869.8 KiB)
Copy the HWaddr to the clipboard (in this case, 06:60:b3:b0:c6:a4)
b. cd examples c. emacs emu-udp-echo-client.cc # or use your favorite editor
Search for the MAC address assigmnet and replace the string with the HWaddr you just found, for example,
ed->SetAddress ("06:60:b3:b0:c6:a4");
Save the changes and build
d. ./waf
In this simple example, we are just going to manually start one ns-3 simulation script to act as a server for a trivial UDP echo application. Once the server is started on [1,1] for example, you can then go to the console for [1,2] and run the UPD echo client script. Let's do it. Remember you don't have all day to dawdle after running the server -- it exits automatically after 60 seconds.
9. Run the server on [1,1]
a. ./waf --run emu-udp-echo-server
10. Run the client on [1,2]
a. ./waf --run emu-udp-echo-client
Congratulations, you have now run your ns-3 simulation scripts on a testbed. That was exciting, wasn't it.
You can now look at the trace files on the client [1,2] and server [1,1] nodes and see what you've done. For example, to look at the pcap traces on the client node:
11. Display the pcap trace on [1,2]
a. cd .. b. tcpdump -nn -tt -r emu-udp-echo-client-0-0.pcap | more
Bonus HOWTO better integrate ns-3 with ORBIT
There are a number of ways that ns-3 could be further integrated with the ORBIT system. Patches are always welcome.
1. Use the ORBIT NodeHandler to drive your experiments: http://www.orbit-lab.org/wiki/Tutorial/HowToCommand
The ORBIT NodeHandler allows you to send shell commands to the various nodes in your experiment. You can use this facility to automate the steps you did manually in the HOWTO above.
2. Support the Orbit Measurement Library (OML): http://www.orbit-lab.org/wiki/Documentation/OML
Using OML, you need to write an XML description of the data you want to collect and compile it. You then get C code that you can link into your ns-3 script that will write your measurement data to the ORBIT database. This could be hooked into the ns-3 tracing framework. See http://www.orbit-lab.org/wiki/Tutorial/CollectingMeasurements
3. Athstats: http://www.orbit-lab.org/wiki/Documentation/Athstats
This is at its lowest level, a Linux program to query the device drivers on the nodes. You can use an ORBIT application to cause this information to be pulled out and stored in the ORBIT OML database during ns-3 driven experiments.
frames transmitted successfully (at senders) frames dropped due to excessive retries (at senders) frames dropped due to FIFO errors (at senders) frames dropped due to filtering (at senders) short retries (for 802.11 RTS frames) (at senders) long retries (for 802.11 DATA/MGMT frames) (at senders) frames received successfully (at receivers) frames dropped due to CRC errors (at receivers) frames dropped due to FIFO errors (at receivers) frames dropped due to PHY errors (at receivers)
4. Use Aruba Sniffers http://www.orbit-lab.org/wiki/Documentation/ARuba
The ORBIT main grid has four Aruba sniffers at the four corners that can be configured to sniff specific channels and report every sniffed packet to the database. This gives the experimenters an independent framework to correlate 802.11 traffic during the course of the experiment for sanity checking as well as verifying the expected outcome of the experiment.
5. Write an ORBIT-specific net device
Right now we can control the settings of the node radios using the usual Linux tools. For example
iwconfig ath0 txpower 30mW
There is a further level of integration with ORBIT available which would require another (ORBIT-specific) device to be written. The ORBIT folks have written a user-space library (libnet + libpcap + API) to allow you to write Ethernet packets, read full 802.11 frames, and get and set interface parameters. See http://www.orbit-lab.org/wiki/Documentation/Libmac
A new net device that uses libmac calls could integrate with the ns-3 Attribute System to allow control of the underlying ORBIT node hardware by the ns-3 script directly.
Craigdo 21:52, 31 December 2008 (UTC)