[[PageOutline]] = GIMI Instrumentation and Measurement Tool: Tutorial Instructions = == Prerequisites == 1. To prepare for the tutorial, each participant should install [https://www.virtualbox.org/ VirtualBox] and the GENI User Workspace image on their computer. Instruction for this step can be found here: [http://groups.geni.net/geni/wiki/GEC14TutorialVMInstructions User Workspace] 2. You should have attended the [http://groups.geni.net/geni/wiki/ORCAExoGENITutorial ExoGENI tutorial] given right before the GIMI tutorial. (Ideally, you would also have attended the [http://groups.geni.net/geni/wiki/GEC14Agenda/OMFTutorial OMF/OML tutorial] given at GEC14. 3. Besides OMF/OML and ExoGENI, this tutorial will make also use of [https://www.irods.org/ iRODS] and [http://ireel.npc.nicta.com.au/ IREEL] and the interested participant can find further information at the links given for both tools. 4. Account information for all tools will be handed out on paper to the participants at the beginning of the tutorial. == Common Errors == * Be careful cutting and pasting * '''Doesn’t work from Trac''' * Sometimes even txt file inserts hidden characters * Some lines require edits; don’t cut and paste the newline * Make terminal windows big * Sometimes terminal gets corrupted when pasting a line that runs to the next line (especially when backspacing) == Getting Ready == * Log into VM with the account name and PW that were given to you on paper handout. * Open Firefox web browser * Open a terminal window * Required SW is already installed in VM: OMF (AM, RC, EC), OML, OMLified Iperf, Nmetrics, iRODS client. * Download GIMI tutorial specific configuration files by issuing the following command in a user workspace terminal: {{{ DILIP TO ADD!! }}} * The iRODS client uses a configuration file (~/.irods/.irodsEnv) that sets certain parameter for the icommands. Here is and example: {{{ # iRODS personal configuration file. # # This file was automatically created during iRODS installation. # Created Thu Feb 16 14:06:27 2012 # # iRODS server host name: irodsHost 'emmy9.casa.umass.edu' # iRODS server port number: irodsPort 1247 # Default storage resource name: irodsDefResource 'iRODSUmass1' # Home directory in iRODS: irodsHome '/geniRenci/home/rods' # Current directory in iRODS: irodsCwd '/geniRenci/home/rods' # Account name: irodsUserName 'gimi01' # Zone: irodsZone 'geniRenci' }}} * Register with iRODS server by issuing the following command (more details on iRODS will be given shortly): {{{ iinit }}} * You will be prompted for a password. Please type in the password you were provided with on the paper handout!! * The image below shows the topology and the interfaces and the routing that has been set up for the measurement: [[Image(wiki:GIMIv1.0Tutorial:Slide12.png)]] == Part 1: OMF/OML on ExoGENI == The goal of this part of the tutorial is to instrument the topology that has been created by the tutorial participants in the preceding ExoGENI tutorial. Perform Iperf and nmetrics measurement on top of that instrumented topology and analyze data from that measurement. * Each node uses the same image but runs a slightly post boot script. The post boot scripts (specified in Flukes) are shown below. * Node A {{{ echo nodeA > /etc/hostname hostname -F /etc/hostname echo 192.168.1.10 nodeA-L1 nodeA >> /etc/hosts echo 192.168.3.10 nodeA-L3 >> /etc/hosts echo 192.168.1.11 nodeB-L1 nodeB >> /etc/hosts echo 192.168.2.11 nodeB-L2 >> /etc/hosts echo 192.168.2.12 nodeC-L2 nodeC >> /etc/hosts echo 192.168.3.12 nodeC-L3 >> /etc/hosts route add -net 192.168.2.0 netmask 255.255.255.0 gw 192.168.1.11 curl http://emmy8.casa.umass.edu/omf-resctl.yaml -o /etc/omf-resctl-5.4/omf-resctl.yaml perl -i.bak -pe "s/\:name\:/\:name\: \'nodeA\' /g" /etc/omf-resctl-5.4/omf-resctl.yaml perl -i.bak -pe "s/\:slice\:/\:slice\: gimi01-gec14/g" /etc/omf-resctl-5.4/omf-resctl.yaml }}} * Node B {{{ echo nodeB > /etc/hostname hostname -F /etc/hostname echo 192.168.1.10 nodeA-L1 nodeA >> /etc/hosts echo 192.168.3.10 nodeA-L3 >> /etc/hosts echo 192.168.1.11 nodeB-L1 nodeB >> /etc/hosts echo 192.168.2.11 nodeB-L2 >> /etc/hosts echo 192.168.2.12 nodeC-L2 nodeC >> /etc/hosts echo 192.168.3.12 nodeC-L3 >> /etc/hosts echo 1 > /proc/sys/net/ipv4/ip_forward curl http://emmy8.casa.umass.edu/omf-resctl.yaml -o /etc/omf-resctl-5.4/omf-resctl.yaml perl -i.bak -pe "s/\:name\:/\:name\: \'nodeB\' /g" /etc/omf-resctl-5.4/omf-resctl.yaml perl -i.bak -pe "s/\:slice\:/\:slice\: gimi01-gec14/g" /etc/omf-resctl-5.4/omf-resctl.yaml }}} * Node C {{{ echo nodeC > /etc/hostname hostname -F /etc/hostname echo 192.168.1.10 nodeA-L1 nodeA >> /etc/hosts echo 192.168.3.10 nodeA-L3 >> /etc/hosts echo 192.168.1.11 nodeB-L1 nodeB >> /etc/hosts echo 192.168.2.11 nodeB-L2 >> /etc/hosts echo 192.168.2.12 nodeC-L2 nodeC >> /etc/hosts echo 192.168.3.12 nodeC-L3 >> /etc/hosts route add -net 192.168.1.0 netmask 255.255.255.0 gw 192.168.2.11 curl http://emmy8.casa.umass.edu/omf-resctl.yaml -o /etc/omf-resctl-5.4/omf-resctl.yaml perl -i.bak -pe "s/\:name\:/\:name\: \'nodeC\' /g" /etc/omf-resctl-5.4/omf-resctl.yaml perl -i.bak -pe "s/\:slice\:/\:slice\: gimi01-gec14/g" /etc/omf-resctl-5.4/omf-resctl.yaml }}} * The images running on the ExoGENI nodes include the following software: * OMF (AM, RC, EC) * OML * OMLified Iperf, nmetrics * iRODS client * For those who would like to use this image as a basis for their own experiment on ExoGENI it can be found here: [http://emmy9.casa.umass.edu/GEC14-GIMI-Tutorial/ http://emmy9.casa.umass.edu/GEC14-GIMI-Tutorial/] * '''Note''' * The OMF experiment controller (EC) that controls the experiment is based on unique host name and experiment name * After initial boot up ExoGENI nodes host names are always initially set to "debian" * The node names will be automatically set to the correct names by a post boot script (defined in Flukes). The code snippet below shows the section of the post boot script that performs this step (for the case of node A) : {{{ echo nodeA > /etc/hostname hostname -F /etc/hostname }}} * The experiment name has to be set to the unique slice name of your ExoGENI request * In the following, we describe the steps to verify the initial topology setup on ExoGENI: * Change the post boot script option to add ''slice name'' as the ''experiment name''. Therefore change the existing experiment name "gec14-gimi01" in line five to the experiment that includes your account name. E.g., if your account name is "gimi05" the experiment name has to be changed to "gimi05-gec14"!! {{{ curl http://emmy8.casa.umass.edu/omf-resctl.yaml -o /etc/omf-resctl-5.4/omf-resctl.yaml perl -i.bak -pe "s/\:name\:/\:name\: \'nodeA\' /g" /etc/omf-resctl-5.4/omf-resctl.yaml perl -i.bak -pe "s/\:slice\:/\:slice\: gimi01-gec14/g" /etc/omf-resctl-5.4/omf-resctl.yaml }}} * Request the ExoGENI slice using Flukes * XMPP The RCs and the EC communicate via an XMPP server. ADD DIAGRAM FROM OMF SITE!! The GIMI XMPP is running on emmy9.casa.umass.edu. * First the ExoGENI instances and the experiment slice should be registered with the XMPP server. You can achieve this using the OMF AM by issuing the following command from a terminal in the user workspace. {{{ omf_create_psnode-5.4 "XMPP Server" mkslice "slice_name" "list_of_nodenames" E.g., omf_create_psnode-5.4 emmy9.casa.umass.edu mkslice gimi01-gec14 nodeA nodeB nodeC }}} In the above command, please change "gimi01" to the user name provided to you. * Login to nodes A, B, and C through Flukes and start the RC deamon by issuing the following command: {{{ /etc/init.d/omf-resctl.5.4 restart }}} * Finally, verify that the RC has been brought up and is listening to the XMPP server by checking the RC log. {{{ cat /var/log/omf-resctl.log }}} * OML Server For this tutorial we have an OML server running on emmy9.casa.umass.edu, which collects the measurement data as an sqlite3 database and at the end of the experiment it pushes the data to IRODS. * Here is how you would have to start an OML server if you wanted to run this on a different machine (OML2.8) is required. DO NOT perform this task in the tutorial!!!! This is explained the [OML installation file]. * Experiment (Finally!) * The experiment will be automatically executed by the OMF EC which is defined by a experiment description file (EDF) written in ruby. * We have prepared the necessary ED files for the experiment described above: LINK TO FILES!! * Before starting the experiment, you need to edit the EC configuration file in you user workspace to have the same slice name as in the RC. You can do that by editing the following file, /etc/omf-expctl-5.4/omf-expctlyaml. Please open the file and edit line 23 to have the "slice name" provide for your ExoGENI request. You can open the file for editing using the following command: {{{ sudo vim /etc/omf-expctl-5.4/omf-expctl.yaml }}} * We start the experiment running the following command from the user workspace terminal: {{{ omf-5.4 exec --no-cmc tcp_iperf.rb -- --source1 nodeA --sink nodeC }}} * VISUALIZATION == Part 2: iRODS - GIMI's Measurement Repository == In GIMI, [https://www.irods.org/ iRODS] is used as the repository for measurement data. At the moment our iRODS data system consist of three servers (RENCI, NICTA, and UMass) and a metadata catalog (located at RENCI). We will use part 2 of this tutorial to make the participants more familiar with iRODS and how we use it in GIMI. * After successful completion of part 1 of the tutorial the measurement data from the experiment has been stored in iRODS. We will now look into two options on how this data can be handled. 1. iRODS command line tools in the user work space: * The GENI [http://groups.geni.net/geni/wiki/GEC14TutorialVMInstructions User Workspace] comes already with the iRODS command line tools installed. * If you have not done so far use [https://www.irods.org/index.php/iinit iinit] to create a file that contains your iRODS password in a scrambled form. This will then be used automatically by the [https://www.irods.org/index.php/icommands icommands] for authentication with the server. {{{ iinit }}} You will be prompted for a password. Please enter the one given on the paper handout. * The iRODS client uses a configuration file (~/.irods/.irodsEnv) that sets certain parameter for the icommands. Here is and example: {{{ # iRODS personal configuration file. # # This file was automatically created during iRODS installation. # Created Thu Feb 16 14:06:27 2012 # # iRODS server host name: irodsHost 'emmy9.casa.umass.edu' # iRODS server port number: irodsPort 1247 # Default storage resource name: irodsDefResource 'iRODSUmass' # Home directory in iRODS: irodsHome '/geniRenci/home/rods' # Current directory in iRODS: irodsCwd '/geniRenci/home/rods' # Account name: irodsUserName 'gimi01' # Zone: irodsZone 'geniRenci' }}} * Retrieve file from iRODS into user workspace. {{{ iget }}} * Store data in user workspace. {{{ iput }}} 2. iRODS web interface: iRODS also provides a nice and easy to use [https://www.irods.org/web/index.php web interface], which we will explore in the following. * Point the browser in your user workspace to the following link: https://www.irods.org/web/index.php * Input the following information to sign in: {{{ Host/IP: emmy9.casa.umass.edu Port: 1247 Username: as given on printout Password: as given on printout }}} 3. IRODS and OML In GIMI we have enabled an option in OML2.8 that allows the execution of script. We use this functionality to automatically save measurement results in IRODS after a measurement has successfully completed. 4. DISCLAIMER The iRODS service we are offering within the scope of GIMI does NOT guarantee 100% reliable data storage (i.e., we do NOT back up the data). If you are performing your own experiments and want to use iRODS you are absolutely welcome but be aware that we do NOT guarantee recovery from data loss. == Part 3: IREEL - GIMI's Measurement Portal == The web portal for GIMI is based on [http://www.nicta.com.au/ NICTA's] [http://ireel.npc.nicta.com.au/ Internet Remote Emulation Experiment Laboratory] (IREEL). We have set up an [http://emmy9.casa.umass.edu:8080/ IREEL instance for GIMI]. * In the GENI User Workspace point your web browser to the following URL: http://emmy9.casa.umass.edu:8080/ * Sign in with the username and password given on the paper handout!