Tutorial 0-2: Using a testbed

TODO

Command help output:

Run a command on the testbed(s)
Usage: omf  [COMMAND] [ARGUMENT]...
  Available COMMANDs:
    help   Print this help message or a specify command usage
    exec   Execute an experiment script
    load   Load a disk image on a given set of nodes
    save   Save a disk image from a given node into a file
    tell   Switch a given set of nodes ON/OFF or reboot them
    stat   Returns the status of a given set of nodes
  To get more help on individual commands: 'omf help [COMMAND]'
  Examples:
            omf  help exec   Return usage/help for the 'exec' command
            omf  help load   Return usage/help for the 'load' command

Connecting to a testbed

TODO

All access to a testbed is done through the testbed's console machine. During the time slot of your approved reservation, you can connect to the console via SSH.

For example, connecting via SSH to yourUserName@sb7.orbit-lab.org will connect you to the console machine of "Sandbox 7".

Loading a disk image onto a node

TODO

Example: Suppose we want to load the baseline disk image onto node1-1 and expand the partition to the full size of the disk in node1-1.

On the console run:

omf load -i baseline.ndz -r -t node1-1

For the "topology" listed after -t, you can specify a single node such as "node1-1", a set of nodes such as "node1-1,node1-3,node1-4", or even a range of nodes such as "[1..2,7..9]" which in this case is equivalent to "node1-7,node1-8,node1-9,node2-7,node2-8,node2-9".

After imaging completes successfully, the nodes will be turned off. They must be turned on before you can SSH into them.

Command help output:

Install a given disk image on the nodes in a testbed
Usage:
      omf load [-h] -t TOPOLOGY [-i IMAGE_PATH] [-o TIMEOUT] [-c AGGREGATE]

      With:
      -h, --help                print this help message
      -t, --topology TOPOLOGY   a valid topology file or description (MANDATORY)
                                (if a file 'TOPOLOGY' doesn't exist, interpret it as a
                                comma-separated list of nodes)
      -i, --image IMAGE         disk image to load
                                (default is 'baseline.ndz', the latest stable baseline image)
      -c, --config AGGREGATE    use testbed AGGREGATE
      -o, --timeout TIMEOUT     a duration (in sec.) after which imageNodes should stop waiting for
                                nodes that have not finished their image installation
                                (default is 800 sec, i.e. 13min 20sec)
      -r, --resize SIZE         Resizes the first partition to SIZE GB or to maximum size if SIZE=0 or
                                leave x percent of free space if SIZE=x%
          --outpath PATH        Path where the resulting Topologies should be saved
                                (default is '/tmp')
          --outprefix PREFIX    Prefix to use for naming the resulting Topologies
                                (default is your experiment ID)

      Some Examples:
                    omf load -t all
                    omf load -t system:topo:all -i baseline-2.4.ndz
                    omf load -t node1-1 -i wireless-2.6.ndz
                    omf load -t [1..10,1..5] -i baseline.ndz -o 400
                    omf load -t system:topo:circle -i my_Own_Image.ndz
                    omf load -t my_Own_Topology -i baseline-2.2.ndz -t 600 -c grid
                    omf load -t my_Own_Topology --outpath ./ --outprefix my_Own_Prefix

Turning nodes on/off

TODO

To turn on node1-1:

omf tell -a on -t node1-1

NOTE: Just like a normal computer, it can take several minutes for a node to finish booting up. Please wait before trying to SSH into it.

To turn off node1-1 as if you held down the power button (ie. hard off):

omf tell -a offh -t node1-1

To reset node1-1 as if your pressed the reset button:

omf tell -a reset -t node1-1

Command help output:

Switch ON/OFF and reboot the nodes in a testbed
Usage:
      omf tell [-h] -t TOPOLOGY -a ACTION [-c AGGREGATE]

      With:
      -h, --help           print this help message

      -a, --action ACTION  specify an action
      ACTION:
      on              turn node(s) ON
      offs            turn node(s) OFF (soft)
      offh            turn node(s) OFF (hard)
      reboot          reboots node(s) (soft)
      reset           resets node(s) (hard)

      -h, --help                print this help message
      -t, --topology TOPOLOGY   a valid topology file or description (MANDATORY)
      -c, --config AGGREGATE    use testbed AGGREGATE

      Some Examples:
                    omf tell -a reset -t node1-1.grid.orbit-lab.org
                    omf tell -a on -t system:topo:all -c grid
                    omf tell -a reboot -t node1-1
                    omf tell -a offh -t [1..2,1..5]
                    omf tell -a offh -t system:topo:all
                    omf tell -a reset -t system:topo:imaged

Accessing a node

TODO

On the console:

ssh root@node1-1

NOTE: If you see an error or warning message while trying to SSH into a node, please read the message. Often times the message has to do with host keys on the node having changed from what the console expects (this is typically normal) because every image has a different host key, therefore it will change depending on what node and image you happen to be using. Follow the instructions in the message to resolve this.

Saving a node's disk image

TODO

If you wish to save a node's disk image for future use, it is important to do so BEFORE your reservation is over because it takes several minutes to complete and there is no guarantee what the next user will do to the node.

Example: Suppose we want to save the disk image of node1-1 on the grid testbed.

First SSH into 'node1-1' and run:

/root/prepare.sh

If you do not run prepare.sh on the node, the disk image WILL NOT WORK when loaded onto another node.

Then on the console run:

omf save -n node1-1.grid.orbit-lab.org

It will take several minutes to complete the save. Once finished, take note of the filename the disk image was saved to (the format of which is username-node-nodename-date-time.ndz) so that you can use it later when loading the disk image again.

Command help output:

Save a disk image from a given node into an archive file
Usage:
      omf save -n NODE [-h] [-c AGGREGATE]

      With:
      -h, --help          print this help message
      -n, --node NODE     a valid description of a single node (MANDATORY)
                          (no default here, you have to enter a node!)
      -r, --resize SIZE   Resizes the first partition to SIZE GB or to maximum size if SIZE=0 or
                          leave x percent of free space if SIZE=x%

      Some Examples:
                    omf save -n node5-3.grid.orbit-lab.org
                    omf save -n node1-1.sb2.orbit-lab.org