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

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



  • OMF5.3Installation

    v1 v1  
     3== 6.  Building and installing software on the WiMAX mobile node  ==
     6This 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
     8We refer to corresponding pages on 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 . 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.
     11=== Table of code, versions;  issues ===
     13The following table shows the hardware/software versions used in the image available at "FILLME".
     15||'''Hardware'''||'''WiMAX Card'''||'''OMF Version'''||'''OML Version'''||'''OS'''||
     16||Dell 1012 Netbook||  Internal Intel 6250  || 5.3 || 2.5.0 || Ubuntu 11.04 ||
     19=== Software components ===
     21The following shows the interaction amongst the different components of the OMF/OML system for the "roaming" MS image.
     23[[Image(OMFCase3Diagram.png, 50%)]]
     25To get a detailed look at OMF please refer to .
     29=== Include OMF/OML services ===
     33In 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.
     35This section is '''OPTIONAL''' as a fully customized image is available with all components installed. The image can be found at "FILLME"
     38==== Setting up the network connections ====
     40- Ensure you have a working Internet connection. (ifconfig ethX)
     42- Remove the network-manager:
     44apt-get remove network-manager
     47(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.
     49- Become superuser by entering
     51sudo -s
     55- Open the file /etc/network/interfaces and configure the loopback interface as follows:
     59        auto lo
     60        iface lo inet loopback
     64- In the same file, configure your wimax interface(e.g. wmx0). Here's an example:
     67        auto wmx0
     68        iface wmx0 inet static
     69        address <ip_addr>
     70        netmask <netmask>
     71        gateway <gateway>
     76- 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).
     78- 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.
     80- 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.
     83==== Configuring XMPP ====
     85The 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.
     87Installing Openfire
     89- Uninstall any other XMPP servers first
     91- Make sure ports TCP 5222, 5269 and 9090 are open in your firewall
     93- Install Java packages
     96apt-get install sun-java6-jre
     99If this package cannot be found, make sure you have enabled the "partner" repository in /etc/apt/sources.list. Then run
     102apt-get update
     104 and retry.
     106Install XMPP openfire software
     109dpkg -i downloadServlet?filename=openfire%2Fopenfire_3.7.0_all.deb
     113- Check if openfire is running:
     115 ps aux | grep openfire
     118Startup can take a while, please be patient.
     120- Direct your web browser to http://localhost:9090 and begin the setup wizard
     122- Choose your language and click continue
     124- Enter the AM's hostname in the Domain field and click continue
     126- Choose the embedded database. You can also use mysql, but you will have to create a mysql user and a database manually first.
     128- Choose the default profile and click continue
     130- Enter an admin password and click continue, then wait until the installation is finished
     132- Log on to the web GUI at http://localhost:9090 with the user/password you set in the wizard
     134- For server2server connectivity, you need to set up a DNS 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.
     137====    Configuring the Aggregate Manager (AM)  ====
     139- add this line to your /etc/apt/sources.list:
     142        deb lucid/
     146- 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.
     150apt-get update
     151apt-get install omf-aggmgr-5.3 oml2-server
     155NOTE: (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.)
     157- The omf-aggmgr service will fail to start. This is normal as we have to configure it first.
     159- 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.
     161Be careful to use only 'spaces' to indent. 'tab' indents are not supported by the ruby yaml parser used to read the file.
     163- If you are running multiple AMs, please configure different XMPP user names for them in omf-aggmgr.yaml.
     165- 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
     167- Enable the following services by creating the following symlinks:
     170        cd /etc/omf-aggmgr-5.3/enabled
     171        ln -s ../available/cmcStub.yaml
     172        ln -s ../available/inventory.yaml
     173        ln -s ../available/result.yaml
     177- Modify the configuration file called /etc/omf-aggmgr-5.3/available/inventory.yaml to reflect your mySQL database configuration
     180====  Inventory Installation  ====
     184apt-get install mysql-server libdb4.6 phpmyadmin
     188- When prompted, enter a mysql root password of your choice or just press enter for no password
     191mysql -u root -p
     195- Paste the following command sequence:
     198use mysql;
     199create user 'omf'@'localhost';
     200grant all on *.* to 'omf'@'localhost';
     201set password for 'omf'@'localhost'=password('omf');
     206- You may obviously use a different user and password, but don't forget to add these to the aggregate manager configuration files later
     208- Start mysql server
     210mysql -u omf -pomf
     213-Create inventory database
     216create database inventory;
     221- 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.
     223- To import the NICTA sample inventory
     226zcat /usr/share/doc/omf-aggmgr-5.3/examples/inventory.sql.gz | mysql -u omf -pomf inventory
     230- 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.
     232- Your inventory database must hold information about the testbed name (e.g. the 'testbeds' table must have an entry corresponding to this name)
     234- For every node in your testbed, you need to add a database record in each of the tables ''locations, motherboards and nodes''
     236- 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.
     238(This needs to be modified with stand-alone inventory sample)
     241====  Creating one pubsub node  ====
     243- 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.
     245- To create the system side of the Pubsub node tree
     247omf_create_psnode-5.3 <AM_name> mksys
     250Replace the first argument with your XMPP server domain, if different from the one used here.
     252- 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.
     254- 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:
     256omf_create_psnode-5.3 <AM_name> mkslice default_slice <wimax_client_name>
     258 to create a "default_slice" containing your single node. Replace the first argument with your XMPP domain.
     260- 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.
     262- Restart OMF aggregate manager
     264/etc/init.d/omf-aggmgr-5.3 restart
     267Restart every time you edited a .yaml file to apply the changes
     270====  Installing the Experiment Controller (EC)  ====
     272- 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:
     274- Ensure the machine you are installing the EC on has internet access
     276- Add this line to your /etc/apt/sources.list:
     279deb lucid/
     283- 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.
     287apt-get update
     288apt-get install omf-expctl-5.3
     293- Copy the default configuration file for the EC
     295zcat /usr/share/doc/omf-expctl-5.3/examples/omf-expctl.yaml.gz > /etc/omf-expctl-5.3/omf-expctl.yaml
     299- 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:
     301- Add your testbed domain and experiment slice name after ':domain:' and ':slice:', e.g. "wimaxlocal" and "default_slice"
     303- Add your XMPP domain in ':communicator:xmpp:pubsub_gateway:', e.g. wimax-cl-1
     305- Add the IP address of a local interface in ':web:host:' to bind the EC's webserver. Use in stand-alone installation.
     307- 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
     309- 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
     311- 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.
     314====   Installing the Resource Controller (RC)  ====
     316- Ensure the machine you are installing the RC on has network access to your XMPP server
     318- Add this line to your /etc/apt/sources.list if it is not there already:
     321        deb lucid/
     325- 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.
     329 apt-get update
     330 apt-get install omf-resctl-5.3
     334- The RC will fail to start. This is normal as we have to configure it first.
     336- 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
     338- Edit /etc/omf-resctl-5.3/omf-resctl.yaml
     340- Enter the name of your control network interface after ':control_if:' (in our case, the loopback interface: lo)
     342- Enter the FQDN or IP address of your XMPP server after ':pubsub_gateway:',
     344- Enter the node's HRN after ':name:', (e.g. 'omf.bbn.node1')
     346- Enter the name of the experiment slice this node is participating in after ':slice:', (e.g. default_slice)
     348- Run /etc/init.d/omf-resctl-5.3 start to start the RC
     350- Check the log file /var/log/omf-resctl-5.3 and see if it successfully registers with the XMPP server
     356=== Include apps for throughput experiment  === 
     358The 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":
     360- Gpslogger_oml2: This is used to capture gps coordinates while conducting outdoor experiments. The application is available at git://  [[BR]]
     362- 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.
     364  - An OML version that does not support the dual mode of operation of iperf.
     365  - An OML version that supports the dual mode operation of iperf.
     366The two versions are not compatible. We have made available separate images with the two different iperf versions at : "FILLME"
     368- wimaxcu: This is an instrumented version of the wimax utility available with the wimax driver that reports the radio parameters on the client side.
     370In 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:
     372  - Create a folder named wiwrapper
     373  - Put the following code segment in a separate file named wiwrapper.rb, and place it in the wiwrapper folder
     374  - Get the file 'oml4r.rb' from
     375  - Put the file 'oml4r.rb' in wiwrapper folder
     376  - Make a tar ball of wiwrapper folder(wiwrapper.tar).
     377  - 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).
     379This is the code for wiwrapper.rb:
     384# Copyright (c) 2011 Raytheon BBN Technologies
     386# Permission is hereby granted, free of charge, to any person obtaining
     387# a copy of this software and/or hardware specification (the "Work") to
     388# deal in the Work without restriction, including without limitation the
     389# rights to use, copy, modify, merge, publish, distribute, sublicense,
     390# and/or sell copies of the Work, and to permit persons to whom the Work
     391# is furnished to do so, subject to the following conditions:
     393# The above copyright notice and this permission notice shall be
     394# included in all copies or substantial portions of the Work.
     403# IN THE WORK.
     406#!/usr/bin/env ruby
     408require 'oml4r'
     411APPNAME = "wimaxcu"
     412APPPATH = "/usr/bin/wimaxcu"
     413APPVERSION = "1.0"
     417class MPStat < OML4R::MPBase
     418    name :wimaxstat
     419    param :CenterFrequency, :type => :long
     420    param :RSSI, :type => :long
     421    param :CINR, :type => :long
     422    param :TXPWR,:type => :long
     424    # wimaxcu returns other metrics which we ignore here
     427class Wrapper
     429  def process_output(output)
     430    # wimaxcu returns a sequence of lines
     431    # The 1st line is a list of labels for the fields of the remaining lines
     432    # Each remaining line is for a detected stations, and follows the format:
     434    lines = output.split("\n")
     435    lines.delete_at(0)
     436    lines.delete_at(1)
     437    lines.delete_at(4)
     438    column =
     439    lines.each { |row|
     440      nums = row.scan(/\d+|-\d+/)
     441      column << nums
     442    }
     444    # Inject the measurements into OML 
     445    MPStat.inject(column[0], column[1], column[2], column[3])
     446  end
     449  def initialize(args)
     451    # Initialise some variable specific to this wrapper
     452    @interval = 5
     454    # Now call the Init of OML4R with the command line arguments (args)
     455    # and a block defining the arguments specific to this wrapper
     456    OML4R::init(args, :appID => APPNAME) { |argParser|
     457      argParser.banner = "\nExecute a wrapper around #{APPNAME}\n" +
     458                         "Use -h or --help for a list of options\n\n" 
     459      argParser.on("-s", "--sampling DURATION", 
     460                   "Interval in second between collected samples") { |time| 
     461                      @interval = time 
     462                   }
     463      argParser.on_tail("-v", "--version", 
     464                        "Show the version\n") { |v| 
     465                           puts "Version: #{APPVERSION}"; exit 
     466                        }
     467    }
     469    # Finally do some checking specific to this wrapper
     470    # e.g. here we do not proceed if the user did not give us a 
     471    # valid interface to monitor
     472    #unless @interface != nil
     473    #  raise "You did not specify an interface to monitor! (-i option)"
     474    #end
     475  end
     477  def start()
     478    while true
     479    # Run the wlanconfig command with the following syntax
     480    #   "wlanconfig <interface> list"
     481    cmd = "#{APPPATH} status link"
     482    output = `#{cmd}`
     483    # Process its output
     484    process_output(output)
     485    # Wait for a given duration and loop again
     486    sleep @interval.to_i
     487   end
     488  end
     492  app =
     493  app.start()
     494rescue Exception => ex
     495  puts "Received an Exception when executing the wrapper!"
     496  puts "The Exception is: #{ex}\n"
     500        For more information on writing wrappers in OMF/OML see:
     506        === Include one or more experiment scripts and "prototypes" === 
     508        Please Refer to the "Writing experiment script" Section: 
     511        ===  Complete build process ===
     514        === Test ===
     517        === OMF Save for image, to archive ===
     520        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.
     522        - On the OMF aggregate manager machine
     524        {{{
     525        omf save -n <node_name>
     526        }}}
     528        - Restart the Wimax MS and the MS will boot from PXE
     530        - The image will be saved on the OMF aggregate manager machine under /var/lib/omf-images-5.3
     532        - Rename the image and re-use if needed.
     537===  Known Issues  ===
     539 - 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.
     541 - 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 and
     543 - 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.
     545 - 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.
     547 - 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.