Referencecm
Reference Component Manager
Overview
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:
git://git-public.flux.utah.edu/reference-cm.git
You may clone the reference CM repository on your local machine anonymously:
git clone git://git-public.flux.utah.edu/reference-cm.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 libxmlsec1-openssl.so.1 /usr/lib/libxmlsec1-openssl.so 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:
- 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.
- 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 emulab.net 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, emulab.net, or any other identifier already chosen for an existing site!), or consult geni-dev@flux.utah.edu 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
http://www.emulab.net/distributions/reference-cm-sample-disk.img.gz
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.
- 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...
- If you are using a working tree obtained by cloning the git repository,
build the configure script by running autoconf:
autoconf
- 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). - Build the reference CM source:
make
- 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.