History

1. OMF 5.4 installation guide

The following steps are necessary to install and configure OMF on Ubuntu 11.10 "oneiric" (32 or 64 bit), which is our preferred OMF installation platform. To install OMF on any other distribution or platform, please see the brief manual installation guidelines at the end of this document. OMF versions 5.4, 5.3 and 5.2 can be installed side-by-side. There are some notes on that scenario in a section below.

System Requirements

  • For the aggregate manager (AM): A PC with two Ethernet interfaces (for control network and internet access)
  • A number of testbed nodes. Each node should have one control network interface (Ethernet) and one or more experiment network interfaces (Ethernet, WLAN, WiMAX, ...). 32MB of RAM is the absolute minimum, 64MB or more is recommended.
  • Although OMF is written in Ruby and should therefore run on any platform that provides a Ruby interpreter, some additional tools (e.g. for loading and saving images) are only provided by us in binary form for the x86 and x86_64 platforms. For other platforms, you need to compile these tools from source.
  • OMF currently supports wireless cards from Atheros (driver ath_pci and ath9k), Cisco (driver airo_pci) and Intel (driver ipw2200). There is also preliminary support for Intel WiMAX client hardware. It is fairly simple to add a wrapper for additional drivers.
  • An Ethernet switch for the control network. Connect the control interfaces of the Aggregate Manager and of each node to this switch.
  • If your experiment network is using Ethernet, you need another switch (or separate VLAN) to link the experiment network interfaces.

Suggested Testbed Layout

Installation of the Aggregate Manager machine

  • Install Ubuntu 11.10 (i386 or amd64) on the AM machine
  • Open a terminal
  • become superuser by entering sudo -s
  • connect the first Ethernet card (eth0) to the Internet
  • connect the second Ethernet card (eth1) to the control network switch

Network Setup

  • ensure you have a working Internet connection on your eth0 interface (ifconfig eth0)
  • on Ubuntu desktop installations, run apt-get remove network-manager (do not run this via SSH since you might lose connectivity)
  • open the file /etc/network/interfaces and configure eth0 for DHCP (or static IP address, depending on your network):
auto eth0                                                                                      
iface eth0 inet dhcp
  • ifup eth0
  • again, ensure you have a working Internet connection on your eth0 interface (ifconfig eth0)
  • apt-get install ssh syslinux dnsmasq ntp
  • configure eth1 to 10.0.0.200. To do that, open /etc/network/interfaces and replace any existing "eth1" section with:
auto eth1                                                                                      
iface eth1 inet static
address 10.0.0.200
netmask 255.255.255.0
  • of course you can use a different IP address or a different local subnet for your control network. This guide will assume 10.0.0.200 for the AM IP address and 10.0.0.0/8 as the subnet.
  • then run ifdown eth1; ifup eth1 and check the interface configuration (ifconfig eth1)

Automatic installation script

You now have the opportunity to skip a few of the next sections and run an automatic installer script for OMF. If you choose to do so, please still read the manual instructions below to understand more about how OMF works and possibly gain the ability to eventually fix problems down the road. If you don't want to use the automatic installation script, please skip to the next section now.

  • download the following files (e.g. using wget) omf_install.rb omf_install.yaml
  • chmod +x omf_install.rb
  • apt-get install ruby
  • open omf_install.yaml in an editor and configure it according to your testbed details
  • make sure you don't violate the YAML file spec
  • the comments in that file describe the parameters
  • save the file and run ./omf_install.rb
  • follow the on-screen instructions
  • the script will pause in the middle and ask you to configure openfire in your web browser. Do not skip this step, the installation will fail if you do.
  • when the installation is finished, please skip to the section Installing the Experiment Controller (EC) below

Configuring dnsmasq (DHCP, DNS and TFTP server)

  • edit /etc/dnsmasq.conf and add the following lines at the bottom of the file:
interface=eth1
dhcp-range=10.0.0.201,10.0.0.254,255.255.255.0,12h
dhcp-option=3
dhcp-option=option:ntp-server,10.0.0.200
dhcp-boot=net:control,pxelinux.0
enable-tftp
tftp-root=/tftpboot
  • the above assumes that you have up to 199 nodes (range 10.0.0.1-10.0.0.199) with static DHCP configuration in a 10.0.0.0/8 subnet. The address range 10.0.0.201-10.0.0.254 is the dynamic DHCP pool for nodes that do not have a static DHCP configuration. There is no default route being sent to the nodes, they only have a route to 10.0.0.0/8 on the control interface.
  • create a new file /etc/dnsmasq.d/testbed.conf and add your node DHCP details here:
dhcp-host=net:control,00:03:2d:08:1a:33,node1,10.0.0.1
dhcp-host=net:control,00:03:2d:08:1a:23,node2,10.0.0.2
dhcp-host=net:control,00:03:2D:0C:FC:B1,node3,10.0.0.3
dhcp-host=net:control,00:03:2d:08:1a:17,node4,10.0.0.4
  • take this example and replace the MAC addresses with the ones from your node's control interfaces
  • replace the hostnames ('nodeX') with your own naming scheme
  • add additional entries according to your local setup
  • /etc/init.d/dnsmasq restart

Set up PXE booting

  • mkdir -p /tftpboot/pxelinux.cfg; ln -s /usr/lib/syslinux/pxelinux.0 /tftpboot/
  • drop the pxe kernel and root filesystem into the /tftpboot directory. Build them yourself from the git repository or download a precompiled release here
  • create the file /tftpboot/pxelinux.cfg/omf-5.4 with the following contents:
SERIAL 0 19200 0
DEFAULT linux
LABEL linux
KERNEL linux-omf-pxe-3.0.4
APPEND console=tty0 console=ttyS0,19200n8 vga=normal quiet root=/dev/ram0 rw load_ramdisk=1 prompt_ramdisk=1 ramdisk_size=32768 initrd=initramfs-omf-pxe-5.4.bz2 control=eth0 xmpp=norbit.npc.nicta.com.au slice=pxe_slice hrn=omf.nicta.%hostname%
PROMPT 0
  • be careful not to wrap any of those lines in the editor
  • make sure the initrd and kernel file names match the ones you've placed in the /tftpboot directory
  • match the control=eth0 parameter to your node hardware. Use the Linux device name of your PXE interface (control interface) here. If you only have one Ethernet card in the nodes, use eth0. If you have more than one card and you don't know the Linux interface name of your control interface, try eth0 first. If you get a message saying "ifconfig: eth0: error fetching interface information: Device not found" when you later on boot from PXE, try eth1 instead (and then eth2, eth3 and so on if you have 3 or 4 or more Ethernet cards).
  • match the xmpp=norbit.npc.nicta.com.au parameter to your setup. This is your XMPP domain (explained at a later stage). Usually it is the FQDN of your AM machine.
  • adjust the "hrn" parameter to the HRN naming scheme of your nodes. E.g. if your node DNS hostnames look like "node1, node2, ..." and your desired HRN names look like "omf.my.node1, omf.my.node2, ...", pass the parameter hrn=omf.my.%hostname% here.
  • the HRN format you choose here has to be the same across your whole OMF installation. It has to be used later on when creating the pubsub resource nodes.
  • create the file /tftpboot/pxelinux.cfg/default containing:
DEFAULT harddrive
LABEL harddrive
localboot 0
  • change directory to /tftpboot/pxelinux.cfg/ and for each node, run ln -s omf-5.4 01-00-03-2D-0D-30-C1 (replace with control network interface MAC address of the node and insert a "01-" in front of it)

At this point you should be able to network-boot your testbed nodes. Enable PXE on the control network interface on each of the nodes via their BIOS and move it to the top of the boot device order. Set your primary hard drive to the second place in the boot order. Now the nodes should receive an IP address via BOOTP and look for a PXE configuration file on the TFTP server. The first filename it looks for is its own MAC address. You have created that symlink in the steps above. If it cannot find such a file on the TFTP server, it will eventually fall back to "default". The "default" file simply instructs the system to boot from the hard drive and not pull any kernel or filesystem image from the TFTP server.

A "tail -f /var/log/syslog" can help troubleshooting BOOTP and TFTP. Use telnet to log on to the network-booted nodes (as root, no password). When booting from PXE, the first console is by default offered via serial port. To access a console locally, press ALT-F2 and enter. On a headless node, connect a serial cable and open a serial terminal software such as gtkterm or minicom to see kernel messages and get a login prompt. Set the port parameters to 38400 8N1.

If you have successfully booted your nodes over the network, remove the MAC address symlinks we created before in /tftpboot/pxelinux.cfg/.

PXE booting works? Fantastic! Continue by following the next steps:

Configuring XMPP

The nodes communicate with the experiment controller via XMPP. Therefore we need to install a XMPP server. It can be installed on the same machine as the AM, but also on any other machine that is reachable from the AM, the experimenter and the nodes.

Installing Openfire

For OMF 5.4, we recommend using Openfire 3.7.1. Other XMPP servers may work as well, but this has not been extensively tested. Ejabberd is known to have some issues regarding node permissions and database cleanup. Openfire seems to be picky about the Java version, we experienced some issues with OpenJDK 6/7, so we currently recommend using SUN Java 6.

  • uninstall any other XMPP servers first
  • make sure ports TCP 5222, 5269 and 9090 are open in your firewall
  • run apt-get install python-software-properties
  • run add-apt-repository ppa:ferramroberto/java; apt-get update; apt-get install sun-java6-jre
  • wget http://www.igniterealtime.org/downloadServlet?filename=openfire/openfire_3.7.1_all.deb
  • run dpkg -i downloadServlet?filename=openfire%2Fopenfire_3.7.1_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 (e.g. norbit.npc.nicta.com.au) 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 resolve from the "outside". 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.
  • if your testbed consists of several hundred nodes, you may consider increasing the maximum open file descriptor limit for the "openfire" user. This can be done by editing /etc/security/limits.conf and adding the lines root soft nofile 100000 and root hard nofile 100000, which allows a maximum of 100K open sockets/files per process. The default in Ubuntu is 1024. If this is not increased you may run into a problem where openfire does not accept any more incoming TCP connections.

Configuring the Aggregate Manager (AM)

  • add this line to your /etc/apt/sources.list:
deb http://pkg.mytestbed.net/ubuntu oneiric/
  • NOTE: If you are using a different version of Ubuntu you might be tempted to replace "oneiric" 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 "oneiric" source. We recommend that you use these packages in combination with Ubuntu oneiric only.
  • apt-get update
  • apt-get install omf-aggmgr-5.4 oml2-server
  • (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.4/examples/omf-aggmgr.yaml to /etc/omf-aggmgr-5.4/ and edit it to enter the correct XMPP server name. The XMPP user account (aggmgr) is created automatically.
  • 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.4/available, if you are at Winlab, copy each file.yaml.winlab to file.yaml.
  • enable each service by creating the following symlinks:
cd /etc/omf-aggmgr-5.4/enabled
ln -s ../available/cmcStub.yaml
ln -s ../available/frisbee.yaml
ln -s ../available/pxe.yaml
ln -s ../available/inventory.yaml
ln -s ../available/result.yaml
ln -s ../available/saveimage.yaml
  • Modify the configuration file called /etc/omf-aggmgr-5.4/available/saveimage.yaml to set up the saveimage interface (set this to your AM's control network IP address)
  • Modify the configuration file called /etc/omf-aggmgr-5.4/available/frisbee.yaml to set up the multicast interface (set this to your AM's control network IP address)

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
  • when prompted, configure phpmyadmin to use apache2
  • run mysql -u root -p and 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
  • run mysql -u omf -pomf and insert the following command sequence:
create database inventory;
quit;
  • to initially populate the inventory database, you may import our sample inventory SQL file. Run zcat /usr/share/doc/omf-aggmgr-5.4/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 InstallationInventory_ for a detailed description of the tables and columns (old 5.2 schema only). 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.
  • Modify the configuration file called /etc/omf-aggmgr-5.4/available/inventory.yaml to reflect your mySQL database configuration

Creating the Pubsub nodes

  • OMF entities use certain Pubsub nodes on the XMPP server to communicate. These nodes must be created before experiments can be run.
  • to create the system side of the Pubsub node tree, run omf_create_psnode-5.4 norbit.npc.nicta.com.au mksys. Replace the first argument with your XMPP server domain.
  • to image the nodes, a slice named "pxe_slice" must be created and all nodes must be added to it. Execute the following command: omf_create_psnode-5.4 norbit.npc.nicta.com.au mkslice pxe_slice omf.nicta.node1 omf.nicta.node2 .... Again replace the first argument with your XMPP domain. List the HRNs of each node in your testbed. To add more nodes later, simply run this command again with the additional nodes as arguments. There will be no duplicates created.
  • 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 same command as before: omf_create_psnode-5.4 norbit.npc.nicta.com.au mkslice default_slice omf.nicta.node1 omf.nicta.node2 ... to create a "default_slice" containing all or some of your nodes.
  • IMPORTANT: this MUST be done for every node that is added to the testbed or slice. If you add more nodes later, don't forget to run this for each of them!
  • if you have multiple testbeds running over the same XMPP server, you should create a default slice for each one of them and choose different slice names
  • if you want to remove a node from the testbed or you've made a mistake creating a system node, don't worry about deleting the system node from the XMPP server. It does no harm to keep them there.
  • execute /etc/init.d/omf-aggmgr-5.4 restart. Run this whenever you edited a .yaml file to apply the changes

Installing the Experiment Controller (EC)

The EC can be installed on the same machine as the AM or on a different one. If its installed on a different machine, make sure the AM services (TCP port 5054) and XMPP (TCP port 5222) are accessible to it. The EC needs to access the XMPP server, and for some experiments also to the nodes directly, so it's best to connect it directly to the control network. If you want to run the EC from a machine outside your organisation, you can provide VPN tunnelling into your control network. This type of setup is not covered in this installation guide.

  • 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 oneiric/
  • NOTE: If you are using a different version of Ubuntu you might be tempted to replace "oneiric" 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 "oneiric" source. We recommend that you use these packages in combination with Ubuntu oneiric only.
  • apt-get update
  • apt-get install omf-expctl-5.4
  • zcat /usr/share/doc/omf-expctl-5.4/examples/omf-expctl.yaml.gz > /etc/omf-expctl-5.4/omf-expctl.yaml
  • the file /etc/omf-expctl-5.4/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. "norbit" and "default_slice"
  • add your XMPP domain in ':communicator:xmpp:pubsub_gateway:'
  • add the IP address of a local interface in ':web:host:' to bind the EC's webserver
  • 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'
  • 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 the OMF authors :)

Installing the omf-web package for experiment visualisation (optional)

If you need experiment visualisation, you can install the additional omf-web-5.4 package.

apt-get install omf-web-5.4

More information can be obtained here: Experiment_Visualisation, or refer to the Hello World tutorials: BasicTutorialStage0-5-4 and BasicTutorialStage0-5-4-wired

Installing the Resource Controller (RC)

The Resource Controller needs to run on your experiment nodes, so they can join experiments that you start with the EC. You can choose to either start with a baseline image for your nodes that is provided by us, or you can choose to create your own image and install the RC in it yourself.

For beginners, we recommend to start with our baseline image. The process to load it onto your nodes is described in the next section.

If you want to create your own image from scratch, install an operating system of your choice on one of your nodes and install the RC on it. You can also install the RC on any existing system, a fresh OS installation is not required. Since the RC is written in Ruby, it should run on almost any platform. However we have only tested it on Linux, and we only provide packages for Ubuntu and Fedora. Generic instructions for other distributions can be found at the bottom of this document.

If you are running Ubuntu, follow these steps to install the 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:
deb http://pkg.mytestbed.net/ubuntu oneiric/
  • NOTE: If you are using a different version of Ubuntu you might be tempted to replace "oneiric" 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 "oneiric" source. We recommend that you use these packages in combination with Ubuntu oneiric only.
  • apt-get update
  • apt-get install omf-resctl-5.4
  • 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.4/examples/omf-resctl.nicta.yaml to /etc/omf-resctl-5.4/omf-resctl.yaml
  • edit /etc/omf-resctl-5.4/omf-resctl.yaml
  • enter the name of your control network interface after ':control_if:' (e.g. eth0)
  • enter the FQDN or IP address of your XMPP server after ':pubsub_gateway:'
  • enter the node's HRN after ':name:'. This can be auto-generated from the hostname or MAC address, as described in the comment in the sample config file
  • enter the name of the experiment slice this node is participating in after ':slice:'
  • run /etc/init.d/omf-resctl-5.4 start to start the RC
  • check the log file /var/log/omf-resctl-5.4 and see if it successfully registers with the XMPP server

To save your custom image and load it onto other nodes, please see the instructions in the following section.

Loading and saving disk images

  • IMPORTANT: at the moment you can only save disks with ext2 or ext3 filesystems. Up to four msdos style (MBR) primary partitions are supported. Disks with other partitioning schemes or other filesystem types cannot be saved using "omf save". If you decide to create your own image from scratch, ensure that you partition it with MBR and install the OS into a primary partition, using ext2 or ext3 filesystem. Ubuntu will choose ext4 by default and may use GPT for EFI based systems.
  • warning: all partitions and all data on the node's disk will be overwritten when you load an image!
  • loading and saving is implemented in an OMF experiment. omf save and omf load will execute the experiment.
  • check the testbeds table in the inventory and make sure you have the correct Linux device name of the node's hard drive in the column "disk" of each node
  • currently, all nodes imaged in a "load" experiment have to have the same disk device name!
  • download our default baseline image from here and place it in /var/lib/omf-images-5.4
  • load the baseline image onto a set of nodes by running omf load -t omf.nicta.node1,omf.nicta.node2,.... Use a comma-separated list of HRNs to select which nodes to image.
  • while you are running omf load for the first time, manually power cycle the nodes that you are imaging. They should now boot into PXE mode and receive instructions to write the hard disk image from the load experiment.
  • after loading has finished, the nodes should boot from their local hard drives. SSH into a node as user "root" with no password.
  • the baseline image we provide assumes that the name of the control network interface is "control" (renamed by udev, see below). If this is different in your setup, log on to the node and change the interface name in /etc/network/interfaces as well as /etc/omf-resctl-5.4/nodehandler.yaml or change the udev rules to rename your device to "control" (see below).
  • save an image from a node (will be uploaded to the /var/lib/omf-images-5.4 directory) with the command omf-5.4 save -n omf.nicta.node1. You can only save the image of one node at a time.
  • the image file ownership will be set to the same user that runs the EC. If EC and AM are on different machines, and the EC user doesn't exist on the AM, the ownership of the image will be set to the ":owner:" configured in saveimage.yaml .

Sample baseline image

  • A baseline image is a "default" or "standard" image, that contains an operating system for the testbed nodes. It has the OMF RC and several other tools preinstalled. Most users can use this baseline image for their experiments without any modifications. However some users may use it as a base for creating their own node image.
  • We are providing a sample baseline image as a courtesy. It has been tested on several different node types at NICTA, but might need modifications if you run it on your hardware. Download it here .
  • The image we provide is configured for our testbed at NICTA. You must adjust some settings in there to your local testbed, particularly the udev rules (see below) and the file /etc/omf-resctl-5.4/omf-resctl.yaml .
  • To build your own baseline image based on ours, you can omf load it onto a node, make local changes there and then omf save it. You can then omf load your newly created image onto the other nodes in the testbed. Please see the Advanced_Tutorials_for_Experimenters on how to use omf load and omf save.
  • The baseline image contains a Ubuntu 11.10 minimal 32bit installation and comes with a pre-installed OMF resource controller.
  • Obviously you are free to use any other Linux distribution on your testbed nodes. Keep in mind though that loading and saving will take longer the more disk space you use. Make sure you format your disk to ext2 or ext3, as other filesystems are not currently supported by imagezip.
  • Our baseline image currently resides on a 9.2 GB ext3 partition with about 8GB of free space.
  • It is important that the control interface and experiment interfaces do not get mixed up at boot time. One way to prevent this is to assign a fixed name to a certain network card using udev. For our local setup, we use these udev rules:
KERNEL=="eth*", DRIVERS=="via-rhine", NAME="eth1" 
KERNEL=="eth*", DRIVERS=="r8169", NAME="eth0" 
KERNEL=="ath*", NAME="%k" 
KERNEL=="wifi*", NAME="%k"

in /etc/udev/rules.d/70-persistent-net.rules which names the control interface "control" and the first experiment interface "exp0". The rule detects the cards by its manufacturer. If you are using different hardware, you might have to come up with your own udev rule for the device naming. The rules for "ath*" and "wifi*" do nothing, they are just here to prevent udev from creating a new rule for wireless cards, which might cause conflicts when the image is loaded onto other nodes.

Using the testbed

Head over to Basic Tutorials for Developing Experiments and follow the tutorial to run your first "Hello World" experiment!

Additional steps (optional)

Openfire Database cleanup

OMF creates many XMPP users, nodes, subscriptions and presence information, which are stored in the Openfire database. In most cases, EC and RC clean up after themselves (i.e. delete temporary nodes and user accounts on shutdown). However there are many situations where this cannot be done, e.g. when a node is reset or an EC is killed. Although we do capture signals, the signal handling code can sometimes not be executed, e.g. when a SIGKILL is sent.

Over time the Openfire database will slowly grow in size, which itself is not really a problem. If you would like to do some cleaning up however, we are providing a script that flushes some of the leftovers from old experiments from the Openfire mySQL database. This script may be run as a cron job during a weekly maintenance slot. You can find it here: source:tools/openfire_cleanup.sh

Approx (Apt Proxy)

This allows you to install Ubuntu packages on the nodes via a proxy on the AM (or any other machine on the control network).

  • apt-get install approx on the AM (or other machine)
  • edit /etc/approx/approx.conf and add your preferred mirrors:
ubuntu          http://mirror.aarnet.edu.au/pub/ubuntu/archive/
security        http://security.ubuntu.com/ubuntu
mytestbed       http://pkg.mytestbed.net/ubuntu
  • edit /etc/apt/sources.list on the nodes and make sure the entries look like this
deb http://10.0.0.200:9999/ubuntu oneiric main restricted
...
deb http://10.0.0.200:9999/security oneiric-security main restricted
...
deb http://10.0.0.200:9999/mytestbed oneiric/
  • this is already configured in our baseline image. You just need to adjust the address of the approx server.

2. FAQ

Please refer to the installation FAQ at FAQ_and_Support

3. OMF 5.3 and 5.4 side-by-side

If you already have OMF 5.3 installed, you can follow this install guide to install 5.4 next to it. Here are some additional hints:

  • if you run both the 5.4 and 5.3 AM, the service calls may be answered by both services. This is a known bug in the 5.3 AM. We recommend to only run the 5.4 AM and shutdown the 5.3 AM.
  • after installing 5.4, the omf command will still call 5.3. To explicitly run 5.4 (or 5.3), use the commands omf-5.4 or omf-5.2 respectively.
  • to change this behaviour, use the update-alternatives script provided by Ubuntu. See its man page for details.
  • the inventory database scheme has changed between the versions. Make sure the database name for 5.4 is different from 5.3 and configure it accordingly in the inventory AM service config.
  • on the node image, 5.3 and 5.4 RCs can run side by side with no problems
  • OEDL syntax has slightly changed as well. Consult the documentation on how to port your experiments to 5.4.

4. Fedora packages

We are providing a yum repository for Fedora Core 8. The RPMs provided there should also work in newer versions of Fedora. Just create a file /etc/yum.repos.d/omf.repo with the following contents:

[OMF]
name=OMF
baseurl=http://pkg.mytestbed.net/rpm/5.4/f8
gpgcheck=0
enabled=1

then run yum update; yum install omf-resctl-5.4 . You may have to create a symlink ln -s /sbin/ifconfig /usr/bin/ifconfig.

5. Installation steps for platforms other than Ubuntu or Fedora

OMF is entirely written in Ruby and should therefore run on any distribution or platform that able to run the Ruby interpreter. Here's a rough guide on how to set up OMF from source.

  • install subversion and Ruby 1.8
  • check out the OMF source code by running git clone git://git.mytestbed.net/omf.git -b release-5.4
  • decide which components of OMF you want to install (AM, EC, RC). All of them depend on omf-common, so you should install this one in any case.
  • to install an OMF component system-wide, enter its folder and copy the subdirectories to your system. Here's an example how a user manually installed the EC:
# create directories
mkdir /usr/share/omf-common-5.4
mkdir /usr/share/omf-expctl-5.4
mkdir /etc/omf-expctl-5.4

# copy files
cp -R omf-common/ruby/* /usr/share/omf-common-5.4/
cp -R omf-expctl/etc/omf-expctl/* /etc/omf-expctl-5.4/
cp -R omf-expctl/ruby/* /usr/share/omf-expctl-5.4/
cp -R omf-expctl/share/* /usr/share/omf-expctl-5.4/
cp -R omf-expctl/bin/* /usr/bin/
cd /usr/bin
ln -s omf omf-5.4
  • follow the same pattern for the AM and RC
  • on platforms such as Windows or OSX, you may want to copy the folders into a local path structure instead of system-wide
  • to install the ruby dependencies, use packages that come with your distribution. If your distribution does not come with a package manager, you can use "gem install", e.g. on Mac OSX. The list of gems can be found in each OMF component's directory, e.g. omf-expctl/ruby/Gemfile
  • the dependencies are as follows (Ubuntu package names, you have to figure out the package names or gem names on your distribution yourself)
omf-common needs:
ruby1.8, liblog4r-ruby, libxmpp4r-ruby

The AM needs:
frisbee, libmysql-ruby, libldap-ruby1.8, libsqlite3-ruby, sqlite3, omf-common, psmisc, nmap, netcat-openbsd

The EC needs:
libmarkaby-ruby, omf-common, libcoderay-ruby, rubygems

The RC needs:
wget, omf-common, wireless-tools, pciutils
  • configure OMF according to the Ubuntu install guide above

6. Experiment Controller on Mac OSX 10.6

  • We provide a package to install the OMF Experiment Controller an a Mac OSX 10.6 system.
  • This package essentially just automate many of the "manual" install steps, which are described in the above section 5.
  • Once the installation is done, you still have to configure your EC, as described in the above section.
  • You can download the latest OSX package for the EC at: