Skip to content. | Skip to navigation

Personal tools


You are here: Home / Wiki / Referencecm


Reference Component Manager

Reference Component Manager


The ProtoGENI team at the University of Utah provides a reference implementation of a component manager to assist others in contributing resources to ProtoGENI. It is deliberately kept less sophisticated than the main (Emulab-based) ProtoGENI software: although it lacks features, it should be more portable and easier to modify than a full Emulab distribution.

The reference CM provides a "toy" set of components, namely a small set of virtual machines (running on the CM host itself). These VMs are not intended to behave as real resources that users would genuinely want to use, but simply as placeholders to demonstrate the CM API and as a test to see that everything is behaving properly.

Obtaining the reference CM

The reference CM distribution is available from Emulab's Git repository at:


You may clone the reference CM repository on your local machine anonymously:

git clone git://

To gain write access to the reference CM repository, follow these instructions.

System dependencies

The reference CM should run on a dedicated (virtual) host. It is intended to be reasonably portable, and should run on most modern Un*x systems. However, a number of other software components are required which may not be part of all Un*x installations:

  • Apache HTTP server (version 2.2 or newer), and mod_ssl
  • GNU Autoconf, version 2.57 or newer (necessary to build the code directly from the git repository; not needed to use release builds)
  • curl (tested with version 7.19)
  • libvirt (tested with version 0.5.1)
  • MySQL (version 5.0 or newer)
  • Perl (version 5 or newer), the suidperl wrapper, and the following Perl modules:
    • Crypt::SSLeay
    • Frontier::RPC
    • RPC::XML
    • Time:: and Date::
    • XML::LibXML and XML::Simple
  • QEMU or another suitable libvirt backend (tested with QEMU version 0.9.1)
  • XMLSec1 (tested with version 1.2.12)

As an example, the following commands will install the dependencies onto a Fedora 10 system. With appropriate modifications, a similar series of commands should also suffice for other platforms.

sudo yum -y install autoconf
sudo yum -y install gcc
sudo yum -y install httpd
sudo yum -y install libvirt
sudo yum -y install mod_ssl
sudo yum -y install mysql-server
sudo yum -y install perl-Crypt-SSLeay
sudo yum -y install perl-Frontier-RPC
sudo yum -y install perl-RPC-XML
sudo yum -y install perl-suidperl
sudo yum -y install perl-TimeDate
sudo yum -y install perl-XML-LibXML
sudo yum -y install perl-XML-Simple
sudo yum -y install qemu
sudo yum -y install xinetd
sudo yum -y install xmlsec1
sudo yum -y install xmlsec1-openssl
sudo ln -s /usr/lib/
sudo /etc/rc.d/init.d/mysqld start
sudo /etc/rc.d/init.d/libvirtd start

(Note that the ln command works around an apparent oversight in the xmlsec1-openssl RPM package, and is hopefully not necessary on most systems.)

Installation of all the dependencies must be completed BEFORE starting configuration of the reference CM.

Configuration and installation

Once you have obtained the reference CM software and installed all the necessary dependencies, you can configure the CM:

  1. Ensure your hostname is properly set. Do not proceed until the hostname command returns a fully qualified domain name which is externally resolvable to a public and routable interface on your host.
  2. Change to the top-level source directory, and copy the defs-example file to another name (e.g. defs-local), and edit the contents of your copy to suit your site:
    • The SSLCERT_ settings will affect all X.509 certificates your site generates. Either choose appropriate strings for your own installation, or consult RFC 5280 or even ITU-T recommendation X.520 to be pedantic.
    • PROTOGENI_DOMAIN and PROTOGENI_AUTHORITY denote the short human-readable-name and DNS domain used to represent your site to the rest of the ProtoGENI federation. For instance, the Emulab installation at the University of Utah uses utahemulab and respectively for these two strings. There is currently no formal registration procedure for these identifiers, although PROTOGENI_AUTHORITY must be a valid DNS domain registered to your organisation. Either choose a reasonable unique pair of strings (do NOT use utahemulab,, or any other identifier already chosen for an existing site!), or consult if you need assistance.
    • ADMIN_EMAIL should be a valid e-mail address to which error messages may be sent.
    • NUM_VIRTUAL_NODES, IMAGE_DIR and BASE_VIRTUAL_IMAGE control the virtual resources provided by the sample back-end. NUM_VIRTUAL_NODES is simply the number of components to be made available: by choosing the default (4), four virtual machines are advertised, named pc0 to pc3. IMAGE_DIR will be used to hold dynamically created disk images for the virtual machines, and should be writable by the UID of the web server. Create the directory now if it does not exist. BASE_VIRTUAL_IMAGE should be the filename of a QEMU disk image to be installed on newly started components. You can supply your own if you have one, or obtain one from
      if you need it (if so, decompress it and then specify the local filename in your defs file). The environment available in that disk image is minimal, but adequate for simple tests. The password for the root account is "geni".
    • LOC_COUNTRY should be set to the ISO 3166 two-letter country code for the country where the components are located. LOC_LAT and LOC_LON are the latitude and longitude (in decimal degrees) north of the equator and east of the Prime Meridian, respectively. The defaults assume your component manager, and therefore the virtual machines, are located at Scott Base in Antarctica. If your host is not at that Antarctic location, please edit these values accordingly.
  3. Remove existing definitions in Apache configuration files for HTTPS virtual hosts listening on port 443 (if any). You can easily do this by deleting (or commenting out) any directives for <VirtualHost _default_:443>, or similar. (Be sure to disable the entire directive, not just the header.) The location of the configuration files varies between distributions. For Fedora 10, it is in /etc/httpd/conf.d/ssl.conf, but other systems place it in /etc/httpd/httpd.conf, /usr/local/etc/apache/httpd.conf, or elsewhere...
  4. If you are using a working tree obtained by cloning the git repository, build the configure script by running autoconf:
  5. Configure the source code with a command like:
    ./configure --with-DEFS=defs-local
    (where defs-local should be replaced with the name of the file you edited earlier).
  6. Build the reference CM source:
  7. With superuser privileges, install and prepare the software:
    make install
    The last step will also prepare databases, configuration files, and register your new component manager. It will ask you to send a public key (generated during this installation process) to the clearinghouse to be used for future authentication, if you haven't done so already. The make install step is designed to be idempotent, so if it does not complete (e.g. because of the necessary registration step), simply run it again until it does.