This page contains instructions for WiMAX site administrators that describe how to GIMI-enable a WiMAX site. If you are looking for instructions on how to use GIMI functionality on a WiMAX site, please see the user instructions.

Overview

A GENI site is considered GIMI-enabled if a user can, without an unreasonable expenditure of effort, use the site to:

• Execute an experiment with OMF
• Instrument an experiment with OML
• Archive experiment measurements to iRODS

The steps required to set up OMF have already been described extensively on this wiki and at ​https://www.mytestbed.net/projects/omf/wiki/Installation, so they will not be covered here. Similarly, the steps required to install an OML server are described ​here.

The steps required to instrument an experiment with OML are already well documented as well. Use these links to find out how to

• Instrument an application that is written in ​C/C++, ​Ruby, or ​Python or
• ​Write a wrapper for an application written in another language, or one whose source code is not available
• Create an ​application definition for your application

This document primarily describes how to provide tools for users to archive an experiment to iRODS. This consists of three parts:

• Installing icommands
• Installing the extra iarchive script
• Setting up iRODS accounts for users
• Extending the OMF experiment controller (optional)
• Installing the iRODS web frontend (optional)

Install icommands

The iRODS software may be downloaded ​here.

Use the irodssetup script inside this package and choose to build only the icommands. Then make these commands available to all users as follows:

cp iRODS/clients/icommands/bin/* /usr/local/bin/

Install iarchive

Download the iarchive script, install it in /usr/local/bin, and make it executable:

wget http://witestlab.poly.edu/repos/misc/iarchive
mv iarchive /usr/local/bin
chmod +x /usr/local/bin/iarchive

If necessary, edit the script and replace the ICMD_PATH, OML_DIR, and EC_LOG_DIR with the relevant values for your system:

• ICMD_PATH is the location where the icommands are installed
• OML_DIR is the location where the OML server stores sq3 files (future version of this script will also accept a URL of an OMF results service)
• EC_LOG_DIR is the location where the OMF experiment controller stores experiment log files

Set up iRODS accounts for users

The administrator for the iRODS server you are using must create an account that is in the rodsadmin group. With this account, you can now create new users using the iadmin commands.

The first time you use this account, you must initialize it using iinit and the values provided by the administrator of the iRODS site you are using. For example:

$ iinit
One or more fields in your iRODS environment file (.irodsEnv) are
missing; please enter them.
Enter the host name (DNS) of the server to connect to:emmy9.casa.umass.edu
Enter the port number:1247
Enter your irods user name:ffund
Enter your irods zone:geniRenci
Those values will be added to your environment file (for use by
other i-commands) if the login succeeds.


Enter your current iRODS password:

Then add a line to your ~/.irods/.irodsEnv file indicating your default resource on the iRODS server. For example:

irodsDefResource=iRODSUmass2

Finally, use ipasswd to change your password from the default password given to you by the iRODS site adminstrator.

Once your account is initialized, use these steps to create new user:

• Temporarily set your irodsHost environment variable to the address of the iCAT server (not necessarily the iRODS server). For example:

  export irodsHost=geni-gimi.renci.org
  

• Use iadmin to create a new user, enroll that use in your site "group", and create an initial password for the user. In this example, we create a user x0dros in the nyupoly group and give him the initial password <password>:

  iadmin mkuser x0dros#geniRenci rodsuser
  iadmin atg nyupoly x0dros#geniRenci
  iadmin moduser x0dros#geniRenci password <password>
  iadmin quit
  

• Finally, unset the temporary irodsHost environment variable:

  unset irodsHost
  

Extend OMF EC (Optional)

You may optionally make some changes to the OMF experiment controller to allow users to archive their last experiment by running iarchive with no arguments.

In /usr/share/omf-expctl-5.3/omf-expctl/experiment.rb add this line in the Experiment class:

  @@user = %x(whoami).downcase.chomp

and modify the Experiment.ID function as follows:

  #
  # Return the ID of this Experiment
  #
  # [Return] the experiment's ID (String)
  #
  def Experiment.ID
    ts = DateTime.now.strftime("%Ft%T%Z").gsub(':','.')
    if (@@expID == nil)
      # since we use the exp ID as the pubsub user name
      # we need to get rid of ":" and uppercase characters
      ts = DateTime.now.strftime("%Ft%T%Z").gsub(':','.')
      @@expID = "#{@@user}-#{@@sliceID}-#{ts}"
      #YTraceState.experiment(:id, @@expID)
    end
 
    File.open(ENV['HOME']+'/.omf-expctl', 'w') do |f2|
      f2.puts "EXP_ID=#{@@expID}"
      f2.puts "SLICE=#{@@sliceID}"
      f2.puts "OMF_USER=#{@@user}"
      f2.puts "OMF_DATE=#{ts}"
      f2.close
    end
 
    return @@expID
  end

Now ever time a user runs an experiment, the EC will create a sourceable file called ".omf-expctl" in the user's home directory. It will look something like this:

EXP_ID=ffund-default_slice-2012-11-06t22.31.47-05.00
SLICE=default_slice
EXP_USER=ffund
EXP_DATE=2012-11-06t22.31.53-05.00