= Tutorial 0-2: Using a testbed =

Most interactions with nodes are done via "OMF commands". These are a simple set of commands used to perform basic functions such as checking node status, turning nodes on/off, loading/saving disk images, or executing experiment scripts (which will be addressed in future tutorials). These OMF commands are performed on the console of the testbed you will be using. As such, the first step is to connect to the testbed console after the time slot for your approved reservation begins.

[[BR]]
== Connecting to a testbed console ==

All access to a testbed is done through the testbed's console machine. You can connect to the console at any time during your approved reservation time slot.

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

[[BR]]
== Checking the status of a node ==

To check the status of ''node1-1'', on the console run:
 {{{omf stat -t node1-1}}}

Which will give output that looks similar to the following
{{{
DEBUG FQDN:console.sb7.orbit-lab.org:
 INFO NodeHandler: OMF Experiment Controller 5.4 (git 861d645)
 INFO NodeHandler: Reading configuration file /etc/omf-expctl-5.4/services.yaml
 INFO NodeHandler: Add domain http - http://internal1.orbit-lab.org:5054/
 INFO NodeHandler: Add domain http - http://repository1.orbit-lab.org:5054/
 INFO NodeHandler: Add domain http - http://external1.orbit-lab.org:5054/
 INFO NodeHandler: Slice ID: default_slice (default)
 INFO NodeHandler: Experiment ID: default_slice-2018-01-24t11.49.44.767-05.00
 INFO NodeHandler: Message authentication is disabled
 INFO Experiment: load system:exp:stdlib
 INFO property.resetDelay: resetDelay = 230 (Fixnum)
 INFO property.resetTries: resetTries = 1 (Fixnum)
 INFO Experiment: load system:exp:eventlib
 INFO Experiment: load system:exp:winlib
 INFO Experiment: load system:exp:stat
 INFO property.nodes: nodes = "node1-1" (String)
 INFO property.summary: summary = false (FalseClass)

Talking to the CMC service, please wait
-----------------------------------------------
 Node: node1-1.sb7.orbit-lab.org         State: POWERON
-----------------------------------------------

 INFO EXPERIMENT_DONE: Event triggered. Starting the associated tasks.
 INFO NodeHandler:
 INFO NodeHandler: Shutting down experiment, please wait...
 INFO NodeHandler:
 INFO run: Experiment default_slice-2018-01-24t11.49.44.767-05.00 finished after 0:5
}}}

You can see the state of node1-1 in this case as "POWERON", meaning that the node is powered on. Other states may say "POWEROFF" to indicate a node is powered off or "NOT REGISTERED" indicating the node was unavailable for use at this time.

[[BR]]
== Loading a disk image onto a node ==

'''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 connect to them.

[[BR]]
== Turning nodes on/off ==

To turn on ''node1-1'':

 {{{omf tell -a on -t node1-1}}}

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.

A clever little shortcut to turning on the nodes that you just imaged is specifying the topology {{{system:topo:imaged}}} which is automatically regenerated every time you perform an imaging operation on a node or set of nodes.

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

 {{{omf tell -a offh -t node1-1}}}

[[BR]]
To reset ''node1-1'' as if your pressed the reset button:

 {{{omf tell -a reset -t node1-1}}}

[[BR]]
== Accessing a node ==

On the console:
 {{{ssh root@node1-1}}}

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.

[[BR]]
== Saving a node's disk image ==

If you wish to save a node's disk image for future use, it is important to do so well 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 in Sandbox 7.

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