Changes between Initial Version and Version 1 of User Guide/Omf Quick Start

Timestamp:

Nov 19, 2019, 4:55:13 PM (4 years ago)

Author:

nilanjan

Comment:

—

User Guide/Omf Quick Start

@@ +1 @@
+
+== OMF Basic Reference
+
+=== A brief overview ===
+
+OMF is a subset of OEDL which is a domain specific language providing a framwork to control and management functionalities for large scale testbeds with multiple networked resources. This framework is implemented as a set of libraries and services mainly written in Ruby. OMF can be used to initiate experiments, control resources & collect live measurements for recording and analysis. The full details for OMF [https://omf.orbit-lab.org/ can be found here.]
+
+To get quickly the sections below describe some of the most used OMF commands in the basic form. These commands are run from the testbed console.
+
+=== OMF usage
+{{{
+console> omf
+
+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 [COMMAND]'
+}}}
+
+
+
+=== OMF status to retrieve status of node(s)
+{{{
+console> omf status
+
+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. This is good way to find all the FQDN of the nodes in the console.
+    {{{omf stat -t all}}}
+
+  Get the status of a single node.
+    {{{omf stat -t sdr2-md1.bed.cosmos-lab.org}}}
+
+  Get the status of multiple nodes. Use a comma-separate list to specify multiple nodes in the topology (no space before or after the comma).
+    {{{omf stat -t sdr2-md1.bed.cosmos-lab.org,srv1-co1.bed.cosmos-lab.org}}}
+
+
+=== OMF tell to power on or off the node(s)
+
+{{{
+console> 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 sdr2-md1.bed.cosmos-lab.org}}}
+
+  Reboot (hard) a node.
+    {{{omf tell -a reboot -t sdr2-md1.bed.cosmos-lab.org}}}
+
+  Turn on multiple nodes.
+    {{{omf tell -a offh -t sdr2-md1.bed.cosmos-lab.org,srv1-co1.bed.cosmos-lab.org}}}
+
+  Turn offh (hard) multiple nodes.
+    {{{omf tell -a offh -t sdr2-md1.bed.cosmos-lab.org,srv1-co1.bed.cosmos-lab.org}}}
+
+
+=== OMF load to install a disk image on the node(s)
+
+{{{
+console> 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 system:topo:all -i baseline.ndz}}}
+
+  Load a specific image (my_image.ndz) on all nodes in a topology.
+
+    {{{omf load -t system:topo:all -i my_image.ndz}}}
+
+  Load a specific image (my_image.ndz) onto a single node.
+
+    {{{omf load -t sdr2-md1.bed.cosmos-lab.org -i my_image.ndz}}}
+
+  Load a specific image (my_image.ndz) onto multiple nodes with a timeout of 400 seconds.
+
+    {{{omf load -t sdr2-md1.bed.cosmos-lab.org,srv1-co1.bed.cosmos-lab.org -i my_image.ndz -o 400}}}
+
+
+=== OMF save to export the disk image from a single node into the repository.
+
+{{{
+console> 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 sdr2-md1.bed.cosmos-lab.org}}}
+
+
+=== omf exec to execute an OEDL script
+
+{{{
+console> 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
+}}}