== OMF Command Reference

=== omf
Run a command on the testbed(s).

Usage:
  {{{omf  [COMMAND] [ARGUMENTS]}}}

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 [COMMAND] -h}}}

Examples:

  Return usage/help for the 'exec' command.
    {{{omf exec -h}}}

  Return usage/help for the 'load' command.
    {{{omf load -h}}}


=== omf stat
Returns the status of the nodes in a testbed.

Usage:
  {{{omf stat [-h] -t TOPOLOGY [-h] [-s] [-c AGGREGATE]}}}

Arguments:
{{{
-h, --help                 print this help message
-t, --topology TOPOLOGY    a valid topology file or description (MANDATORY)
-s, --summary              print a summary of the node status for the testbed
-c, --config AGGREGATE     use testbed AGGREGATE
}}}

Examples:

  Get the status of all nodes in the testbed.
    {{{omf stat -t all}}}

  Get the status of a node.
    {{{omf stat -t node1-1.grid.orbit-lab.org}}}

  Get the status of a range of nodes.
    {{{omf stat -t [1..2,1..2]}}}

  Get the status of a topology.
    {{{omf stat -t system:topo:all -c grid}}}

=== omf tell
Switch ON/OFF and reboot the nodes in a testbed.

Usage:
  {{{omf tell [-h] -t TOPOLOGY -a ACTION [-c AGGREGATE]}}}

Arguments:
{{{
-h, --help                 print this help message
-a, --action ACTION        specify an 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)
-t, --topology TOPOLOGY    a valid topology file or description (MANDATORY)
-c, --config AGGREGATE     use testbed AGGREGATE
}}}

Examples:

  Reset (soft) a node.
    {{{omf tell -a reset -t node1-1.grid.orbit-lab.org}}}

  Reboot (hard) a node.
    {{{omf tell -a reboot -t node1-1}}}

  Turn off (hard) all nodes in a range.
    {{{omf tell -a offh -t [1..2,1..5]}}}

  Turn off (hard) all nodes in a topology.
    {{{omf tell -a offh -t system:topo:all}}}

  Reset (soft) all nodes in a topology.
    {{{omf tell -a reset -t system:topo:imaged}}}

=== omf load
Install a given disk image on the nodes in a testbed.

Usage:
  {{{omf load [-h] -t TOPOLOGY [-i IMAGE_PATH] [-o TIMEOUT] [-c AGGREGATE]}}}

Arguments:
{{{
-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)
}}}

Examples:

  Load the default baseline image (baseline.ndz) on all nodes in the testbed.
    {{{omf load -t all}}}

  Load a image on all nodes in a topology.
    {{{omf load -t system:topo:all -i baseline-2.4.ndz}}}

  Load an image onto a node.
    {{{omf load -t node1-1 -i wireless-2.6.ndz}}}

  Load an image onto a range of nodes with a timeout of 400 seconds.
    {{{omf load -t [1..10,1..5] -i baseline.ndz -o 400}}}

  Load an image onto all nodes in a topology.
    {{{omf load -t system:topo:circle -i my_Own_Image.ndz}}}

  Load an image onto all nodes in a topology.
    {{{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}}}


=== omf save
Save a disk image from a given node into an archive file.

Usage:
  {{{omf save -n NODE [-h] [-c AGGREGATE]}}}


Arguments:
{{{
-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%
}}}

NODE must be specified in FQDN (fully qualified domain name) format (eg. node1-1.sb1.orbit-lab.org).

Examples:

  Save the disk image from a node.
    {{{omf save -n node5-3.grid.orbit-lab.org}}}

    {{{omf save -n node1-1.sb2.orbit-lab.org}}}

=== omf exec
Execute an experiment script.

Usage:
  {{{exec [OPTIONS] ExperimentName [-- EXP_OPTIONS]}}}

!ExperimentName is the filename of the experiment script

[EXP_OPTIONS] are any options defined in the experiment script

[OPTIONS] are any of the following:
{{{
-a, --allow-missing              Continue experiment even if some nodes did not check in
-c, --config NAME                Configuration section from the config file ('default' if omitted)
-C, --configfile FILE            File containing local configuration parameters
-d, --debug                      Operate in debug mode
-i, --interactive                Run the experiment controller in interactive mode
-l, --libraries LIST             Comma separated list of libraries to load (defaults to [system:exp:stdlib,system:exp:eventlib,system:exp:winlib])
--log FILE                       File containing logging configuration information
-m, --message MESSAGE            Message to add to experiment trace
-n, --just-print                 Print the commands that would be executed, but do not execute them
-N, --no-am                      Don't use the Aggregate Manager (AM)
-p, --print URI                  Print the contents of the experiment script
-o, --output-result FILE         File to write final state information to
-e, --experiment-id EXPID        Set the ID for this experiment, instead of the default standard ID
-O, --output-app                 Display STDOUT & STDERR output from the executed applications
-r, --reset                      If set, then reset (reboot) the nodes before the experiment
-s, --shutdown                   If set, then shut down resources at the end of an experiment
-S, --slice NAME                 Name of the Slice where this EC should operate
-t, --tags TAGS                  Comma separated list of tags to add to experiment trace
--oml-uri URI                    The URI to the OML server for this experiment
-x, --extra-libs LIST            Comma separated list of libraries to load in addition to [system:exp:stdlib,system:exp:eventlib,system:exp:winlib]
--slave-mode EXPID               Run in slave mode in disconnected experiment, EXPID is the exp. ID
--slave-mode-resource NAME       When in slave mode, NAME is the HRN of the resource for this EC
-h, --help                       Show this message
-v, --version                    Show the version
}}}