Changes between Initial Version and Version 1 of OMF5.3Installation

Timestamp:

09/07/11 17:24:34 (13 years ago)

Author:

agosain@bbn.com

Comment:

--

OMF5.3Installation

@@ +1 @@
+[[PageOutline]]
+
+== 6.  Building and installing software on the WiMAX mobile node  ==
+
+
+This page describes the installation of a stand-alone OMF (cOntrol and Management Framework) setup on a single node, and the setup required to perform basic WiMAX experiments on a mobile node. Experiments can also be performed using a custom built image which includes the entire software suite and is available by contacting the GPO at gpo-infra@geni.net. 
+
+We refer to corresponding pages on http://mytestbed.net/ occasionally in this document, so that the interested reader could compare/follow the related procedures. However, there are important differences between what we have here and the pages on http://mytestbed.net/ . We believe that having all the steps we took to create WiMAX experiments in one place reduces possible confusions for a new experimenter who wants to replicate our setup.
+
+
+=== Table of code, versions;  issues ===
+
+The following table shows the hardware/software versions used in the image available at "FILLME".
+
+||'''Hardware'''||'''WiMAX Card'''||'''OMF Version'''||'''OML Version'''||'''OS'''||
+||Dell 1012 Netbook||  Internal Intel 6250  || 5.3 || 2.5.0 || Ubuntu 11.04 ||
+
+
+=== Software components ===
+
+The following shows the interaction amongst the different components of the OMF/OML system for the "roaming" MS image.
+
+[[Image(OMFCase3Diagram.png, 50%)]]
+
+To get a detailed look at OMF please refer to http://mytestbed.net/projects/omf .
+
+
+
+=== Include OMF/OML services ===
+
+
+
+In this section we describe how to install all of the OMF components on a single machine, as opposed to the traditional use of OMF managing a testbed of many different nodes. This is required because there is no reliable control channel available for the mobile node that only has a wimax interface. The "roaming" node wired connection is unplugged after the image load process to enable mobile experiments. 
+
+This section is '''OPTIONAL''' as a fully customized image is available with all components installed. The image can be found at "FILLME"
+
+
+==== Setting up the network connections ====
+
+- Ensure you have a working Internet connection. (ifconfig ethX)
+
+- Remove the network-manager: 
+{{{
+apt-get remove network-manager
+}}}
+ 
+(do not run this via SSH since you might lose connectivity). Make sure you are able to assign static IP addresses to the interfaces manually, and that the changes remain in place after reboot.
+
+- Become superuser by entering 
+{{{
+sudo -s
+}}}
+
+
+- Open the file /etc/network/interfaces and configure the loopback interface as follows:
+
+
+{{{
+        auto lo
+        iface lo inet loopback
+
+}}}
+
+- In the same file, configure your wimax interface(e.g. wmx0). Here's an example:
+
+{{{
+        auto wmx0
+        iface wmx0 inet static
+        address <ip_addr>
+        netmask <netmask>
+        gateway <gateway>
+
+
+}}}
+
+- Save your changes, bring down lo and wmx0 interfaces, bring them back on and check to see if your changes have taken effect (ifconfig wmx0, ifconfig lo).
+
+- You do not need to configure "dnsmasq" for stand-alone OMF installation. If you're also following the installation guide on OMF website, skip the dnsmasq part.
+
+- You do not need to setup "PXE booting" for stand-alone OMF installation. If you're also following the installation guide on OMF website, skip the "Setup PXE booting" part.
+        
+
+==== Configuring XMPP ====
+
+The communication of the "node" and the "Experiment Controller" (EC) happens through via XMPP. Consequently, you'll need to have an XMPP server running on the machine as well. For OMF-5.3, Openfire 3.7 XMPP server is recommended.
+
+Installing Openfire
+
+- Uninstall any other XMPP servers first
+
+- Make sure ports TCP 5222, 5269 and 9090 are open in your firewall
+
+- Install Java packages 
+
+{{{
+apt-get install sun-java6-jre
+}}}
+
+If this package cannot be found, make sure you have enabled the "partner" repository in /etc/apt/sources.list. Then run 
+
+{{{
+apt-get update
+}}}
+ and retry.
+
+Install XMPP openfire software
+{{{
+wget http://www.igniterealtime.org/downloadServlet?filename=openfire/openfire_3.7.0_all.deb
+dpkg -i downloadServlet?filename=openfire%2Fopenfire_3.7.0_all.deb
+}}}
+
+
+- Check if openfire is running:
+{{{
+ ps aux | grep openfire
+}}}
+
+Startup can take a while, please be patient.
+
+- Direct your web browser to http://localhost:9090 and begin the setup wizard
+
+- Choose your language and click continue
+
+- Enter the AM's hostname in the Domain field and click continue
+
+- Choose the embedded database. You can also use mysql, but you will have to create a mysql user and a database manually first.
+
+- Choose the default profile and click continue
+
+- Enter an admin password and click continue, then wait until the installation is finished
+
+- Log on to the web GUI at http://localhost:9090 with the user/password you set in the wizard
+
+- For server2server connectivity, you need to set up a DNS name "pubsub.yourhost.name" which can be resolved from the public internet. It can be an A record pointing to the same IP address as your host, or a CNAME pointing to the hostname. There is no need for a DNS SRV record.
+
+
+====    Configuring the Aggregate Manager (AM)  ====
+
+- add this line to your /etc/apt/sources.list:
+
+{{{
+        deb http://pkg.mytestbed.net/ubuntu lucid/
+}}}
+ 
+
+- NOTE: If you are using a different version of Ubuntu you might be tempted to replace "lucid" with your version here(e.g. maverick). That repository however may contain a different version of OMF. This document only applies if you use the packages from the "lucid" source. We recommend that you use these packages in combination with Ubuntu lucid only.
+
+ 
+{{{
+apt-get update
+apt-get install omf-aggmgr-5.3 oml2-server
+}}}
+
+
+NOTE: (the OML server is installed to collect measurement data for the result service. You don't need to install it if you are not planning to use OML and the result service.)
+
+- The omf-aggmgr service will fail to start. This is normal as we have to configure it first.
+
+- Copy the example configuration file /usr/share/doc/omf-aggmgr-5.3/examples/omf-aggmgr.yaml to /etc/omf-aggmgr-5.3/ and edit it to enter the correct XMPP server name. The XMPP user account (aggmgr) is created automatically. An example of for the ':server' field, under ':xmpp' would be "wimax-cl-1", that is our hostname.
+
+Be careful to use only 'spaces' to indent. 'tab' indents are not supported by the ruby yaml parser used to read the file. 
+
+- If you are running multiple AMs, please configure different XMPP user names for them in omf-aggmgr.yaml. 
+
+- In the directory /etc/omf-aggmgr-5.3/available, copy each file that is named file.yaml.nicta to file.yaml, unless you are at Winlab, where you copy each file.yaml.winlab to file.yaml
+
+- Enable the following services by creating the following symlinks:
+        
+{{{
+        cd /etc/omf-aggmgr-5.3/enabled
+        ln -s ../available/cmcStub.yaml
+        ln -s ../available/inventory.yaml
+        ln -s ../available/result.yaml
+
+}}}
+
+- Modify the configuration file called /etc/omf-aggmgr-5.3/available/inventory.yaml to reflect your mySQL database configuration
+
+
+====  Inventory Installation  ====
+
+- 
+{{{
+apt-get install mysql-server libdb4.6 phpmyadmin
+
+}}}
+
+- When prompted, enter a mysql root password of your choice or just press enter for no password
+ 
+{{{
+mysql -u root -p
+}}}
+
+
+- Paste the following command sequence:
+        
+{{{
+use mysql;
+create user 'omf'@'localhost';
+grant all on *.* to 'omf'@'localhost';
+set password for 'omf'@'localhost'=password('omf');
+quit;
+
+}}}
+
+- You may obviously use a different user and password, but don't forget to add these to the aggregate manager configuration files later 
+
+- Start mysql server 
+{{{
+mysql -u omf -pomf
+}}}
+ 
+-Create inventory database
+        
+{{{
+create database inventory;
+quit;
+}}}
+
+
+- To initially populate the inventory database, you may import NICTA's sample inventory SQL file. It contains all the necessary tables and is filled with sample entries from one of our sandboxes. You may edit it to your needs before or after importing it.
+
+- To import the NICTA sample inventory
+
+{{{
+zcat /usr/share/doc/omf-aggmgr-5.3/examples/inventory.sql.gz | mysql -u omf -pomf inventory
+
+}}}
+
+- You should now be able to open your browser at http://localhost/phpmyadmin/ and log on as omf/omf. Have a look at the inventory database tables to get a feel for what goes in there. Check "Installation Inventory_" for a detailed description of each table. Modify the inventory contents to match your setup accordingly.
+
+- Your inventory database must hold information about the testbed name (e.g. the 'testbeds' table must have an entry corresponding to this name)
+
+- For every node in your testbed, you need to add a database record in each of the tables ''locations, motherboards and nodes''
+
+- The inventory requires some manual work, and describing each step would take this quick installation guide too far. If you are reasonably convinced that you've filled the tables correctly, please proceed with the guide. You can optimize the inventory at a later stage.
+
+(This needs to be modified with stand-alone inventory sample)
+
+
+====  Creating one pubsub node  ====
+
+- OMF entities use certain Pubsub nodes on the XMPP server to communicate. These nodes must be created before experiments can be run. In our case, which is an stand-alone installation, we only need to create one such node.
+
+- To create the system side of the Pubsub node tree
+{{{
+omf_create_psnode-5.3 <AM_name> mksys
+}}}
+
+Replace the first argument with your XMPP server domain, if different from the one used here.
+
+- In non-stand-alone setups of OMF, in order to image the nodes, a slice named "pxe_slice" must be created and all nodes must be added to it. We are not interested in that when considering a stand-alone installation so we skip that at this stage. If you want to have this option available for any reason, consult OMF-5.3 installation guide at "Creating the pubsub nodes" section.
+
+- Regular experiments are executed in a slice as well. To run an experiment on a set of nodes, they must be added to that slice first. Use the following command for this purpose: 
+{{{
+omf_create_psnode-5.3 <AM_name> mkslice default_slice <wimax_client_name>
+}}}
+ to create a "default_slice" containing your single node. Replace the first argument with your XMPP domain. 
+
+- If you want to remove the node from your stand-alone single-node testbed or you've made a mistake creating the system node, don't worry about deleting the system node from the XMPP server. It does no harm to keep them there.
+
+- Restart OMF aggregate manager
+{{{
+/etc/init.d/omf-aggmgr-5.3 restart
+}}}
+
+Restart every time you edited a .yaml file to apply the changes
+
+
+====  Installing the Experiment Controller (EC)  ====
+
+- Before installing the EC on the local machine, make sure that the AM services (TCP port 5053) and XMPP (TCP port 5222) are accessible to it. Follow the following steps for installation of ECs:
+
+- Ensure the machine you are installing the EC on has internet access
+
+- Add this line to your /etc/apt/sources.list:
+        
+{{{
+deb http://pkg.mytestbed.net/ubuntu lucid/
+}}}
+ 
+
+- NOTE: If you are using a different version of Ubuntu you might be tempted to replace "lucid" with your version here. That repository however may contain a different version of OMF. This document only applies if you use the packages from the "lucid" source. We recommend that you use these packages in combination with Ubuntu lucid only.
+
+
+{{{
+apt-get update
+apt-get install omf-expctl-5.3
+}}}
+
+
+
+- Copy the default configuration file for the EC 
+{{{
+zcat /usr/share/doc/omf-expctl-5.3/examples/omf-expctl.yaml.gz > /etc/omf-expctl-5.3/omf-expctl.yaml
+}}}
+
+
+- The file /etc/omf-expctl-5.3/omf-expctl.yaml has multiple configuration sections for different testbeds. In this guide we will only look at section :default:
+
+- Add your testbed domain and experiment slice name after ':domain:' and ':slice:', e.g. "wimaxlocal" and "default_slice" 
+
+- Add your XMPP domain in ':communicator:xmpp:pubsub_gateway:', e.g. wimax-cl-1
+
+- Add the IP address of a local interface in ':web:host:' to bind the EC's webserver. Use 127.0.0.1 in stand-alone installation.
+
+- Add the contact details of your OML server (if you followed this guide it is running on the AM machine) in ':omluri:' in format 'protocol:hostname:port', e.g. tcp:localhost:3003
+
+- If you have legacy HTTP AM services running on this machine or other machines, add their URLs to 'inventory:url:', ':cmc:url' and so on
+
+- If you are unsure about the configuration parameters, please contact your testbed administrator. If you are the administrator and you are still unsure, please do not hesitate to contact us.
+
+
+====   Installing the Resource Controller (RC)  ====
+
+- Ensure the machine you are installing the RC on has network access to your XMPP server
+
+- Add this line to your /etc/apt/sources.list if it is not there already:
+
+{{{
+        deb http://pkg.mytestbed.net/ubuntu lucid/
+}}}
+ 
+
+- NOTE: If you are using a different version of Ubuntu you might be tempted to replace "lucid" with your version here. That repository however may contain a different version of OMF. This document only applies if you use the packages from the "lucid" source. We recommend that you use these packages in combination with Ubuntu lucid only.
+
+
+{{{
+ apt-get update
+ apt-get install omf-resctl-5.3
+}}}
+
+
+- The RC will fail to start. This is normal as we have to configure it first.
+
+- Copy the example configuration file /usr/share/doc/omf-resctl-5.3/examples/omf-resctl.nicta.yaml to /etc/omf-resctl-5.3/omf-resctl.yaml
+
+- Edit /etc/omf-resctl-5.3/omf-resctl.yaml
+
+- Enter the name of your control network interface after ':control_if:' (in our case, the loopback interface: lo)
+
+- Enter the FQDN or IP address of your XMPP server after ':pubsub_gateway:',
+
+- Enter the node's HRN after ':name:', (e.g. 'omf.bbn.node1')
+
+- Enter the name of the experiment slice this node is participating in after ':slice:', (e.g. default_slice)
+
+- Run /etc/init.d/omf-resctl-5.3 start to start the RC
+
+- Check the log file /var/log/omf-resctl-5.3 and see if it successfully registers with the XMPP server
+
+
+
+
+
+=== Include apps for throughput experiment  ===  
+                 
+The OML developers have modified the source code of the following applications to include Measurement Points (MP) that can be stored in OML databases. Our experiments use the following applications that are available in the image "FILLME": 
+         
+- Gpslogger_oml2: This is used to capture gps coordinates while conducting outdoor experiments. The application is available at git://git.mytestbed.net/oml-apps.git  [[BR]] 
+ 
+- oml2_iperf: This is an instrumented version of iperf that sends traffic over the wimax interface to measure throughput. Currently there are two versions of oml2_iperf. 
+         
+  - An OML version that does not support the dual mode of operation of iperf. 
+  - An OML version that supports the dual mode operation of iperf. 
+The two versions are not compatible. We have made available separate images with the two different iperf versions at : "FILLME" 
+         
+- wimaxcu: This is an instrumented version of the wimax utility available with the wimax driver that reports the radio parameters on the client side. 
+         
+In order to be able to properly use wimaxcu link status reports in the experiment, we will have to write an OMF wrapper around it as 'wimaxcu' does not come with OML support. To create the wrapper: 
+         
+  - Create a folder named wiwrapper 
+  - Put the following code segment in a separate file named wiwrapper.rb, and place it in the wiwrapper folder 
+  - Get the file 'oml4r.rb' from http://mytestbed.net/repositories/changes/oml/lib/client/ruby/oml4r.rb 
+  - Put the file 'oml4r.rb' in wiwrapper folder 
+  - Make a tar ball of wiwrapper folder(wiwrapper.tar). 
+  - Put the tar ball, wiwrapper.rb, and oml4r.rb in the same directory as that of your experiment (we assume this is the directory you run your experiments from). 
+          
+This is the code for wiwrapper.rb: 
+                 
+{{{ 
+
+#----------------------------------------------------------------------
+# Copyright (c) 2011 Raytheon BBN Technologies
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and/or hardware specification (the "Work") to
+# deal in the Work without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense,
+# and/or sell copies of the Work, and to permit persons to whom the Work
+# is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Work.
+#
+# THE WORK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+# WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE WORK OR THE USE OR OTHER DEALINGS
+# IN THE WORK.
+#----------------------------------------------------------------------
+
+#!/usr/bin/env ruby 
+$LOAD_PATH<<'/usr/bin' 
+require 'oml4r' 
+                 
+                 
+APPNAME = "wimaxcu" 
+APPPATH = "/usr/bin/wimaxcu" 
+APPVERSION = "1.0" 
+                 
+                 
+                 
+class MPStat < OML4R::MPBase 
+    name :wimaxstat 
+    param :CenterFrequency, :type => :long 
+    param :RSSI, :type => :long 
+    param :CINR, :type => :long 
+    param :TXPWR,:type => :long 
+                 
+    # wimaxcu returns other metrics which we ignore here 
+end 
+                 
+class Wrapper 
+         
+  def process_output(output) 
+    # wimaxcu returns a sequence of lines 
+    # The 1st line is a list of labels for the fields of the remaining lines 
+    # Each remaining line is for a detected stations, and follows the format: 
+    # ADDR AID CHAN RATE RSSI DBM IDLE TXSEQ RXSEQ CAPS ACAPS ERP STATE MODE 
+    lines = output.split("\n") 
+    lines.delete_at(0) 
+    lines.delete_at(1) 
+    lines.delete_at(4) 
+    column = Array.new 
+    lines.each { |row| 
+      nums = row.scan(/\d+|-\d+/) 
+      column << nums 
+    } 
+         
+    # Inject the measurements into OML  
+    MPStat.inject(column[0], column[1], column[2], column[3]) 
+  end 
+                 
+         
+  def initialize(args) 
+             
+    # Initialise some variable specific to this wrapper 
+    @interval = 5 
+         
+    # Now call the Init of OML4R with the command line arguments (args) 
+    # and a block defining the arguments specific to this wrapper 
+    OML4R::init(args, :appID => APPNAME) { |argParser| 
+      argParser.banner = "\nExecute a wrapper around #{APPNAME}\n" + 
+                         "Use -h or --help for a list of options\n\n"  
+      argParser.on("-s", "--sampling DURATION",  
+                   "Interval in second between collected samples") { |time|  
+                      @interval = time  
+                   } 
+      argParser.on_tail("-v", "--version",  
+                        "Show the version\n") { |v|  
+                           puts "Version: #{APPVERSION}"; exit  
+                        } 
+    } 
+                 
+    # Finally do some checking specific to this wrapper 
+    # e.g. here we do not proceed if the user did not give us a  
+    # valid interface to monitor 
+    #unless @interface != nil 
+    #  raise "You did not specify an interface to monitor! (-i option)" 
+    #end 
+  end 
+         
+  def start() 
+    while true 
+    # Run the wlanconfig command with the following syntax 
+    #   "wlanconfig <interface> list" 
+    cmd = "#{APPPATH} status link" 
+    output = `#{cmd}` 
+    # Process its output 
+    process_output(output) 
+    # Wait for a given duration and loop again 
+    sleep @interval.to_i 
+   end 
+  end 
+end 
+         
+begin 
+  app = Wrapper.new(ARGV) 
+  app.start() 
+rescue Exception => ex 
+  puts "Received an Exception when executing the wrapper!" 
+  puts "The Exception is: #{ex}\n" 
+end 
+}}} 
+         
+        For more information on writing wrappers in OMF/OML see: http://mytestbed.net/wiki/omf/OMLWrapperHowTo 
+         
+         
+                 
+                 
+                 
+        === Include one or more experiment scripts and "prototypes" ===  
+         
+        Please Refer to the "Writing experiment script" Section:  
+        http://groups.geni.net/syseng/wiki/OMF5.3Experiment
+         
+        ===  Complete build process === 
+                 
+                 
+        === Test === 
+         
+         
+        === OMF Save for image, to archive === 
+                 
+         
+        The experiment described above is a sample. The motivation is for experimenters to develop new experiments using the framework described above. Once the experimenters have modified the scripts and created new experiments on the Wimax MS, they will need to save their work for repeating experiments. 
+         
+        - On the OMF aggregate manager machine 
+                 
+        {{{ 
+        omf save -n <node_name> 
+        }}} 
+                 
+        - Restart the Wimax MS and the MS will boot from PXE 
+         
+        - The image will be saved on the OMF aggregate manager machine under /var/lib/omf-images-5.3 
+                 
+        - Rename the image and re-use if needed. 
+ 
+
+                 
+
+===  Known Issues  ===
+
+ - There is an incompatibility with OMF and OML at the moment. Newer version of OML uses more precise data types, but OMF is not yet aware of them. NICTA's aware of the problem and is working on a unification solution. In the mean-time, a short fix is to use ":long" instead of "uint32" and ":float" instead of ":double", similar to what we did with the new iperf OMF application. OML still supports these old types, but this is for transition only, and will at some point be deprecated.
+
+ - If you receive the following error:  'undefined method `stdin' for nil:NilClass' after using the new iperf in your experiment, you might need to make a small change in your OMF Code. Check http://mytestbed.net/issues/526 and http://mytestbed.net/projects/omf/repository/revisions/331c8c6ecedd02d07b7f60c72f6bffa0c0febbdf 
+ 
+ - We have not yet investigated the use of OMF Disconnected Mode to perform mobile experiments. However, there seems to be issues when one wants to direct the results of an OMF experiment to multiple OML servers/proxies. This feature has to be operational if we want to use the visualization service while performing an experiment in disconnected mode.
+
+ - The recent version of OML is 2.6, but as you've probably noticed, we have used OML 2.5.0 in our setup. The reason is that we were facing problems compiling the new, comprehensive iperf code when OML 2.6. was installed/used. The main problem was that OML library files did not seem to be correctly installed. 
+
+ - Our set up does not yet work with external wimax cards. This is because OMF internally uses lsusb to detect whether a wimax device is available and sometimes external devices (such as an external wimax card) are not listed by that command. Attempts are being made to resolve the issue.
+
+
+
+
+
+
+
+
+