Difference between revisions of "HOWTO use ns-3 in the ORBIT testbed environment"

From Nsnam
Jump to: navigation, search
Line 134: Line 134:
 
     defGroup('server', [1,1]) { |node|
 
     defGroup('server', [1,1]) { |node|
 
       node.image = "ns-3.3.ndz"
 
       node.image = "ns-3.3.ndz"
−
      node.net.w0.mode = "master"
 
−
      node.net.w0.type = "g"
 
−
      node.net.w0.essid = "ns-3"
 
 
     }
 
     }
 
      
 
      
 
     defGroup('client', [1,2]) { |node|
 
     defGroup('client', [1,2]) { |node|
 
       node.image = "ns-3.3.ndz"
 
       node.image = "ns-3.3.ndz"
−
      node.net.w0.mode = "managed"
 
−
      node.net.w0.type = "g"
 
−
      node.net.w0.essid = "ns-3"
 
 
     }
 
     }
 
      
 
      
 
     whenAllUp() { |node|
 
     whenAllUp() { |node|
 +
      allGroups.exec("/usr/local/bin/wlanconfig ath0 destroy")
 +
      wait 2
 +
      group("server").exec("/usr/local/bin/wlanconfig ath0 create wlandev wifi0 wlanmode ap")
 +
      wait 2
 +
      group("client").exec("/usr/local/bin/wlanconfig ath0 create wlandev wifi0 wlanmode sta")
 +
      wait 2
 +
      allGroups.exec("ifconfig ath0 promisc up")
 +
      wait 2
 
       allGroups.exec("cd /home/repos/ns-3.3; hg pull http://code.nsnam.org/craigdo/ns-3.3-orbit; hg update; ./waf")
 
       allGroups.exec("cd /home/repos/ns-3.3; hg pull http://code.nsnam.org/craigdo/ns-3.3-orbit; hg update; ./waf")
 
       wait 500
 
       wait 500
Line 152: Line 154:
 
     }
 
     }
  
−
     ''Sidebar:  Note the "wait 500" statement in the above code.  There is''
+
     ''Sidebar:  Note the wait statements in the above code.  There is''
−
     ''apparently no way to execute a command synchronously.  Thus, we seem''
+
     ''apparently no way to execute a command synchronously on multiple nodes''
−
     ''faced with a tradeoff.  Either ssh into the nodes and perform the''
+
     ''using ORBIT tools.  Thus, we seem  faced with a tradeoff.  Either ssh''
−
     ''actions manually and synchronously, or automate them and possibly''
+
    '' into the nodes and perform the actions manually and synchronously,''
−
     ''wait longer than absolutely necessary.''
+
     ''or automate them and possibly wait longer than absolutely necessary.''
 +
     ''It seems safe to control-C out of the script after the compilations''
 +
    ''are done.''
  
−
xxxxxx
+
2.  Execute the ns-3-prepare.rb command script.
 +
    a.  orbit exec ns-3-prepare
  
 +
    INFO init: NodeHandler Version 4.2.0 (1272)
 +
    INFO init: Experiment ID: sb1_2009_01_12_20_34_55
 +
    INFO Experiment: load system:exp:stdlib
 +
    INFO prop.resetDelay: resetDelay = 210:Fixnum
 +
    INFO prop.resetTries: resetTries = 1:Fixnum
 +
    INFO Experiment: load ns-3-prepare
 +
    INFO stdlib: Waiting for nodes (Up/Down/Total): 0/2/2 - (still down: n_1_2,n_1_1)
 +
    ...
 +
    INFO whenAll: *: 'status[@value='UP']' fires
 +
    INFO whenAll: *: 'status[@value='UP']' fires
 +
    INFO exp: Request from Experiment Script: Wait for 10s....
 +
    Event DONE.OK (from /usr/local/bin/wlanconfig@n_1_2): status: 0
 +
    Event DONE.OK (from /usr/local/bin/wlanconfig@n_1_1): status: 0
 +
    INFO exp: Request from Experiment Script: Wait for 10s....
 +
    ...
 +
    INFO exp: Request from Experiment Script: Wait for 500s....
 +
    Message (from cd@n_1_2):  pulling from http://code.nsnam.org/craigdo/ns-3.3-orbit
 +
    Message (from cd@n_1_2):  searching for changes
 +
    Message (from cd@n_1_2):  no changes found
 +
    ...
 +
    familiar waf output from ns-3
 +
    ...
 +
    Event DONE.OK (from cd@n_1_1): status: 0
 +
    INFO Experiment: DONE!
 +
    INFO ExecApp: Application 'commServer' finished
 +
    INFO run: Experiment sb1_2009_01_12_20_34_55 finished after 10:35
  
−
 
+
Notice that this script has taken care of setting up the wireless devices
−
2.  Connect to node [1,1] and configure its wireless
+
for you.
−
    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  
 
Now you can run the example ns-3 client server scripts on the testbed.  We have  
Line 200: Line 203:
 
of the interfaces in the ns-3 simulation script.
 
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]
+
3.  Set the hardware address of the interface in the server script on node [1,1]
 
     a. ifconfig
 
     a. ifconfig
  
Line 227: Line 230:
 
     d.  ./waf
 
     d.  ./waf
  
−
9.  Set the hardware address of the interface in the client script on node [1,2]
+
4.  Set the hardware address of the interface in the client script on node [1,2]
 
     a. ifconfig
 
     a. ifconfig
  
Line 260: Line 263:
 
to dawdle after running the server -- it exits automatically after 60 seconds.
 
to dawdle after running the server -- it exits automatically after 60 seconds.
  
−
9.  Run the server on [1,1]
+
5.  Run the server on [1,1]
 
     a.  ./waf --run emu-udp-echo-server
 
     a.  ./waf --run emu-udp-echo-server
  
−
10.  Run the client on [1,2]
+
6.  Run the client on [1,2]
 
     a.  ./waf --run emu-udp-echo-client
 
     a.  ./waf --run emu-udp-echo-client
  
Line 273: Line 276:
 
node:
 
node:
  
−
11. Display the pcap trace on [1,2]
+
7. Display the pcap trace on [1,2]
 
     a. cd ..
 
     a. cd ..
 
     b. tcpdump -nn -tt -r emu-udp-echo-client-0-0.pcap  | more
 
     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.
 
  
 
----
 
----
  
−
[[User:Craigdo|Craigdo]] 21:52, 31 December 2008 (UTC)
+
[[User:Craigdo|Craigdo]] 02:28, 13 January 2009 (UTC)

Revision as of 02:28, 13 January 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.

In HOWTO use ns-3 directly on the ORBIT testbed hardware we showed how to use the ORBIT hardware as a basis for ns-3 experiments. This HOWTO shows how one can use ORBIT tools to automate the process of getting an experiment run.

We assume that you have some experience with the ORBIT system and understand the basic environment. 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. We further assume that you have at least read the HOWTO use ns-3 directly on the ORBIT testbed hardware and understand what it is we are trying to automate here.

HOWTO use ns-3 in the ORBIT testbed environment

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 ns-3.3 repository, emacs editor, etc. The first step is to get this environment up on the nodes in your testbed. In ORBIT terminology, we need to "image the nodes."

1. Connect to the sandbox console, image the sandbox nodes and power them up 

   a.  ssh your-orbit-user-name@console.sb1.orbit-lab.org;
   b.  orbit load all ns-3.3.ndz

This is a somewhat time-consuming process since you are actually copying disk images to the sandbox nodes. The example below took about seven 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.3.ndz'
       (Domain:  default from hostname)
       (Timeout:  800 sec.)
       INFO init: NodeHandler Version 4.2.0 (1272)
       INFO init: Experiment ID: sb1_2008_12_30_21_25_31
       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.3.ndz":String
       INFO prop.pxe: pxe = "1.2.1-omf":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_2,n_1_1)
       ...
       INFO whenAll: *: 'status[@value='UP']' fires
       INFO exp: Progress(0/0/2): 0/0/0 min(n_1_2)/avg/max (91) - Timeout: 700 sec.
       ...
       INFO exp: Progress(2/0/2): 100/100/100 min()/avg/max (91) - Timeout: 358 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_2008_12_30_21_25_31 finished after 7:28

You can now take a look at the status of the nodes. Observe that they are in the POWEROFF state 

   c.  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 need to wait until this process has completed. One way to do this is to ping the sandbox nodes.

2. Ping the sandbox nodes to make sure they are up. 

   a.  ping -c 1 node1-1

   PING node1-1.sb1.orbit-lab.org (10.11.1.1) 56(84) bytes of data.
   64 bytes from node1-1.sb1.orbit-lab.org (10.11.1.1): icmp_seq=1 ttl=64 time=0.422 ms
   
   --- node1-1.sb1.orbit-lab.org ping statistics ---
   1 packets transmitted, 1 received, 0% packet loss, time 0ms
   rtt min/avg/max/mdev = 0.422/0.422/0.422/0.000 ms

   b.  ping -c 1 node1-2

   PING node1-2.sb1.orbit-lab.org (10.11.1.2) 56(84) bytes of data.
   64 bytes from node1-2.sb1.orbit-lab.org (10.11.1.2): icmp_seq=1 ttl=64 time=3.62 ms
   
   --- node1-2.sb1.orbit-lab.org ping statistics ---
   1 packets transmitted, 1 received, 0% packet loss, time 0ms
   rtt min/avg/max/mdev = 3.624/3.624/3.624/0.000 ms

Now, you can write a simple ruby script to go out and pull the updated ns-3 code from the repository. Using your favorite editor, copy the following code into a file called "ns-3-prepare.rb": 

   Experiment.name = "ns-3-prepare"
   
   defGroup('server', [1,1]) { |node|
     node.image = "ns-3.3.ndz"
   }
   
   defGroup('client', [1,2]) { |node|
     node.image = "ns-3.3.ndz"
   }
   
   whenAllUp() { |node|
     allGroups.exec("/usr/local/bin/wlanconfig ath0 destroy")
     wait 2
     group("server").exec("/usr/local/bin/wlanconfig ath0 create wlandev wifi0 wlanmode ap")
     wait 2
     group("client").exec("/usr/local/bin/wlanconfig ath0 create wlandev wifi0 wlanmode sta")
     wait 2
     allGroups.exec("ifconfig ath0 promisc up")
     wait 2
     allGroups.exec("cd /home/repos/ns-3.3; hg pull http://code.nsnam.org/craigdo/ns-3.3-orbit; hg update; ./waf")
     wait 500
     Experiment.done
   }

   Sidebar:  Note the wait statements in the above code.  There is
   apparently no way to execute a command synchronously on multiple nodes
   using ORBIT tools.  Thus, we seem  faced with a tradeoff.  Either ssh
    into the nodes and perform the actions manually and synchronously,
   or automate them and possibly wait longer than absolutely necessary.
   It seems safe to control-C out of the script after the compilations
   are done.

2. Execute the ns-3-prepare.rb command script. 

   a.  orbit exec ns-3-prepare

   INFO init: NodeHandler Version 4.2.0 (1272)
   INFO init: Experiment ID: sb1_2009_01_12_20_34_55
   INFO Experiment: load system:exp:stdlib
   INFO prop.resetDelay: resetDelay = 210:Fixnum
   INFO prop.resetTries: resetTries = 1:Fixnum
   INFO Experiment: load ns-3-prepare
   INFO stdlib: Waiting for nodes (Up/Down/Total): 0/2/2 - (still down: n_1_2,n_1_1)
   ...
   INFO whenAll: *: 'status[@value='UP']' fires
   INFO whenAll: *: 'status[@value='UP']' fires
   INFO exp: Request from Experiment Script: Wait for 10s....
   Event DONE.OK (from /usr/local/bin/wlanconfig@n_1_2): status: 0
   Event DONE.OK (from /usr/local/bin/wlanconfig@n_1_1): status: 0
   INFO exp: Request from Experiment Script: Wait for 10s....
   ...
   INFO exp: Request from Experiment Script: Wait for 500s....
   Message (from cd@n_1_2):  pulling from http://code.nsnam.org/craigdo/ns-3.3-orbit
   Message (from cd@n_1_2):  searching for changes
   Message (from cd@n_1_2):  no changes found
   ...
   familiar waf output from ns-3
   ...
   Event DONE.OK (from cd@n_1_1): status: 0
   INFO Experiment: DONE!
   INFO ExecApp: Application 'commServer' finished
   INFO run: Experiment sb1_2009_01_12_20_34_55 finished after 10:35

Notice that this script has taken care of setting up the wireless devices for you.

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.

3. 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

4. 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.

5. Run the server on [1,1] 

   a.  ./waf --run emu-udp-echo-server

6. 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:

7. Display the pcap trace on [1,2] 

   a. cd ..
   b. tcpdump -nn -tt -r emu-udp-echo-client-0-0.pcap  | more

Craigdo 02:28, 13 January 2009 (UTC)

Retrieved from "https://www.nsnam.org/mediawiki/index.php?title=HOWTO_use_ns-3_in_the_ORBIT_testbed_environment&oldid=2286"