Simple OMF ping experiment

This simple example introduces you to OMF6. It presents all the basic steps to develop, run, and access the results of an experiment executed with OMF 6.

This tutorial is based on UTH NITlab scenario (Simple OMF Example) - adapted to use in FIT-NITOS Paris platform and portal.onelab.eu

Experiment Description

This simple experiment involves a single node, which has an active network interface. In this experiment, we will instruct that node to start an instance of the traditional Linux /bin/ping application to probe another host on the network attached to that interface (in our case Google’s DNS server).

Prerequisites

Provisioning and accessing resources

Before starting this tutorial, please make sure that you have completed the following:

• You need to have active account on the OneLab portal (to create an account please follow this tutorial: User sign-up)
• You need to create or join existing project (Please follow this tutorial: Lab)
• You need to create or join existing slice within the project (Please follow this tutorial: Experiment )
• You need to reserve one node on FIT NITOS Paris (to know how to reserve node please follow this tutorial: reservation-with-scheduling-label)
• You have SSH client installed (on OSX and Linux the terminal clients are available by default, on Windows you can donwload and install Putty). Alternatively if you are using Mozilla Firefox or Google Chrome you can install this plugin to run shell within browser. See more here: Accessing reserved resources

Experiment Controller (EC)

The OMF Experiment Controller (EC) is the software that will interpret your Experiment Description (ED) and interact with the resources to execute it accordingly. You can run your experiment directly from EC installed on our gateway server (in this case please skip this section) or you can install EC on your own machine by following this tutorial: OMF 6 Installation Guide.

Preparing an experiment

In order to run an experiment using OMF, you first need to describe it with an Experiment Description (ED). An ED is a file/script that is supplied as an input to the Experiment Controller (EC). It contains a detailed description of the resources involved in the experiment and the sets of actions to perform in order to realize that experiment. An ED is written using the OMF Experiment Description Language (OEDL). You can click here to know more about (OMF6-OEDL).

In this tutorial we will use already prepared ED file. Please follow the comments to understand the code. Please update this code with node name that you have reserved.

# 1. Define an OMF Application Definition for the ping-oml2 application
# The OMF entities are using this definition to know where to find the
# application, what are its configurable parameters, and what are the
# OML2 measurement points that it provides.
# This ping-oml2 application will be known by OMF entities as 'ping_oml2'
#
defApplication('simple_ping') do |app|
  app.description = 'Simple Definition for the simple_ping application'
  # Define the path to the binary executable for this application
  app.binary_path = '/bin/ping'
  # Define the configurable parameters for this application
  # For example if target is set to foo.com and count is set to 2, then the
  # application will be started with the command line:
  # /bin/ping -a foo.com -c 2
  app.defProperty('target', 'Address to ping', '', {:type => :string})
  app.defProperty('count', 'Number of times to ping', '-c', {:type => :integer})
end

# 2. Define a group of resources which will run the ping-oml2 application
# Here we define only one group (Sender), which has only one resource in it
# (node11)
#
##### UPDATE THIS SCRIPT WITH NODE NAME THAT YOU HAVE RESERVED ###########
defGroup('Sender', 'node11') do |g|
  # Associate the application ping_oml2 defined above to each resources
  # in this group
  g.addApplication("simple_ping") do |app|
    # Configure the parameters for the ping_oml2 application
    app.setProperty('target', '8.8.8.8')
    app.setProperty('count', 3)
    # Request the ping_oml2 application to collect measurement samples
    # from the 'ping' measuremnt point (as defined above), and send them
    # to an OML2 collection point
    app.measure('ping', :samples => 1)
  end
end

# 3. Define the sequence of tasks to perform when the event
# "all resources are up and all applications are install" is being triggered
#
onEvent(:ALL_UP_AND_INSTALLED) do |event|
  # Print some information message
  info "This is my first OMF experiment"
  # Start all the Applications associated to all the Groups
  allGroups.startApplications
  # Wait for 5 sec
  # Stop all the Applications associated to all the Groups
  after 15 do
    allGroups.stopApplications
   end
  # Tell the Experiment Controller to terminate the experiment now
  after 10 do
    Experiment.done
  end
end

Running an experiment

To run your experiment you need to have Experiment Controler (EC) installed and configured. As mentioned before you can always use EC installed by us on testbed gateway server: paris.fit-nitos.fr. We will follow this aproach in this tutorial.

Accessing your account on the gateway server

1. Download SSH private key form the portal that was generated for you during account creation:

   • login to portal,
   • In your profile, click “Download Private Key” button.

   

2. If you have an active Nitos/OMF reservation, go to portal dashboard and under Your current reservation, click “Go to your reservation”. You will be redirected to your Nitos Experiment.

   

Your user-specific SSH command will appear in this page. This command will let you access through SSH to the resources

NOTE: You need to have SSH client installed (on OSX and Linux the terminal clients are available by default, on Windows you can donwload and install Putty). Alternatively you may also run shell within browser (Mozilla Firefox or Google Chrome only). To know how to access your reserved nodes on different Operating Systems please follow this tutorial: Accessing reserved resources

Cleaning up the environment

NITOS nodes are Ubuntu based PC’s with enabled Wi-Fi cards. You should start your experiment with installing clean copy of Ubuntu OS. To achieve this please run the command:

omf load -i baseline.ndz -t nodeXX #loading OMF enabled Ubuntu OS image on the nodeXX (replace nodeXX with node name that you have reserved)

At any time you can turn on the node and connect to it with standard ssh command (no authorisation is required):

omf tell -a on -t nodeXX # turn on the nodeXX
ssh root@nodeXX  # XX should be replaced by the node number

Than you can install on the node any new software you like. However when the reservation period will expire we don’t remove the software installed by user. For this reason before running your experiment we asked you to install clean copy of Ubuntu OS.

Hint: If you install some specific software on the node and you would like to preserve your work you can always save whole disk image into the file (you can skip this during our tutorial and go directly to “Running your ED script from EC” section).

omf save -n nodeXX #saving OMF image for the nodeXX

The image will be stored in /home/images on the gateway server (example file: root-node-node11.paris.fit-nitos.fr-25_11_2014_14:57.ndz). In addition you can deploy the same image on all nodes that you have reserved:

omf load -i root-node-node11.paris.fit-nitos.fr-25_11_2014_14:57.ndz -t nodeXX,nodeZZ,nodeYY #loading OMF image on the nodeXX, nodeZZ, nodeYY

To know more options please run command:

omf load

Running your ED script from EC

1. On the gateway server copy-paste the script to file paris_tutorial000.rb or download ED_script

   wget http://doc.onelab.eu/_downloads/paris_tutorial000.rb
   

2. Update the ED file with your reserved node name (using nano or vim). In this script you need to change node name to the one you have reserved (line 24). Hint: to save your work with nano you need to press ctrl+x and then press ‘Y’ on your keyboard and hit <ENTER>.

   nano paris_tutorial000.rb
   

2. Start the EC software and tell it to execute the experiment described in your ED file, using the command line:

   omf_ec -u xmpp://griffin.ipv6.lip6.fr exec paris_tutorial000.rb
   

If you would like to know more about the other options of the OMF EC software please run the commands:

omf_ec help
omf_ec help exec

Understanding the output

Below is the example output from the experiment that we have defined and run as part of this experiment:

• At first the EC provides us with some information about the parameters of this experiment:

onelab.upmc.nitos_tut.nitos@griffin:~$ omf_ec -u xmpp://griffin.ipv6.lip6.fr exec test.rb
OMF Experiment Controller - Copyright (c) 2012-13 National ICT Australia Limited (NICTA)
{:type=>:xml, :authenticate=>nil}
15:41:58 INFO  XMPP::Communicator: Connecting to 'griffin.ipv6.lip6.fr' ...
15:42:03 INFO  XMPP::Communicator: Connected
15:42:03 INFO  Object: OMF Experiment Controller 6.1.1 - Start
15:42:03 INFO  Object: Connected using {:proto=>:xmpp, :user=>"griffin-21097", :domain=>"griffin.ipv6.lip6.fr"}
15:42:03 INFO  Object: Execute: /home/onelab.upmc.nitos_tut.nitos/test.rb
15:42:03 INFO  Object: Properties: {}
15:42:03 WARN  Context::AppContext: No OML URI configured for measurement collection! (see option 'oml_uri'). Disabling OML Collection for 'ping'.
15:42:03 INFO  OmfEc::Experiment: Experiment: 2015-05-29T13:41:58.229Z starts
15:42:03 INFO  OmfEc::Experiment: Configure 'node11' to join 'Sender'

• It provides us some feedback about its communication with the xmpp server and other OMF entities.It also informs us when a defined event has been triggered:

15:42:03 INFO  OmfEc::Experiment: Newly discovered resource >> xmpp://node11@griffin.ipv6.lip6.fr
15:42:03 INFO  OmfEc::Experiment: Config xmpp://node11@griffin.ipv6.lip6.fr to join Sender
15:42:04 INFO  OmfEc::Experiment: Event triggered: 'ALL_NODES_UP, ALL_UP'
15:42:04 INFO  OmfEc::Experiment: Newly discovered resource >> xmpp://4a66bb92-97b3-4229-96b5-3652c6021449@griffin.ipv6.lip6.fr

• Finally, when an event is triggered (such as ALL_UP_AND_INSTALLED), it informs us about the tasks executed for that event, and their results/outputs:

15:42:04 INFO  OmfEc::Experiment: Event triggered: 'ALL_UP_AND_INSTALLED'
15:42:04 INFO  Object: This is my first OMF experiment
15:42:04 INFO  OmfEc: APP_EVENT STARTED from app simple_ping_cxt_0 - msg: env -i /bin/ping  8.8.8.8 -c 3
15:42:04 INFO  OmfEc: APP_EVENT STDOUT from app simple_ping_cxt_0 - msg: PING 8.8.8.8 (8.8.8.8) 56(84) bytes of data.
15:42:04 INFO  OmfEc: APP_EVENT STDOUT from app simple_ping_cxt_0 - msg: 64 bytes from 8.8.8.8: icmp_req=1 ttl=53 time=5.18 ms
15:42:05 INFO  OmfEc: APP_EVENT STDOUT from app simple_ping_cxt_0 - msg: 64 bytes from 8.8.8.8: icmp_req=2 ttl=53 time=26.5 ms
15:42:06 INFO  OmfEc: APP_EVENT STDOUT from app simple_ping_cxt_0 - msg: 64 bytes from 8.8.8.8: icmp_req=3 ttl=53 time=37.4 ms
15:42:06 INFO  OmfEc: APP_EVENT STDOUT from app simple_ping_cxt_0 - msg:
15:42:06 INFO  OmfEc: APP_EVENT STDOUT from app simple_ping_cxt_0 - msg: 3 packets transmitted, 3 received, 0% packet loss, time 2002ms
15:42:06 INFO  OmfEc: APP_EVENT STDOUT from app simple_ping_cxt_0 - msg: --- 8.8.8.8 ping statistics ---
15:42:06 INFO  OmfEc: APP_EVENT STDOUT from app simple_ping_cxt_0 - msg: rtt min/avg/max/mdev = 5.182/23.081/37.482/13.416 ms
15:42:06 INFO  OmfEc: APP_EVENT EXIT from app simple_ping_cxt_0 - msg: 0
15:42:14 INFO  OmfEc::Experiment: Experiment: 2015-05-29T13:41:58.229Z finished
15:42:14 INFO  OmfEc::Experiment: Release applications and network interfaces
15:42:14 INFO  OmfEc::Experiment: Exit in 15 seconds...
15:42:28 INFO  OmfEc::Experiment: OMF Experiment Controller 6.1.1 - Exit.
15:42:29 INFO  XMPP::Communicator: Disconnecting...

• You can access same results by going to /tmp directory on the server:

cd /tmp
ls -ltr
cat 2015-05-29T13:41:58.229Z.log