Skip to content. | Skip to navigation

Personal tools


You are here: Home / Wiki / Referencecminemulab


Reference Component Manager in Emulab

Reference Component Manager in Emulab


An Emulab can be a convenient environment for testing and running the reference Component Manager. The major benefit is that it can be a very quick way to get a CM up, since the Utah Emulab has custom images which allow booting of a system fairly quickly (within a few minutes) which has all software and dependencies loaded and ready for configuration.

Experimental setup

To construct a reference CM inside Emulab, you must apply for an Emulab account if you do not have one already. You must apply for membership in the geni project. You should then start an experiment with an NS file similar to this:

set ns [new Simulator]
source tb_compat.tcl

set host [$ns node]
tb-set-node-os $host PROTOGENI-REF-CM
tb-set-node-tarfiles $host /usr/src

$ns run

The important commands are the tb-set-node-os and the tb-set-node-tarfiles: the PROTOGENI-REF-CM image includes a base (Fedora 10) system with all the necessary ProtoGENI dependencies. The CM itself is not included in the image, but distributed in the source tar.gz file installed subsequently (it is kept independent, to allow the choice of alternative reference CM versions as they become available).

The example ns file above will install the CM source under /usr/src/reference-cm-2.0.2, although other directories would work equally well.


Once you have swapped in the experiment, you should log in to the single host, and follow the standard CM configuration procedure:

  1. Change to the top-level source directory (i.e. /usr/src/reference-cm-2.0.2 in the example above), 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, so either choose a reasonable pair of strings, 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). If you are planning to swap the experiment out and back in at any point, then it is probably easiest to keep the disk image in an experimental directory somewhere under /proj, to avoid losing it after a swap out.
    • 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.
  2. 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 in the previous step).
  3. Build the reference CM source:
  4. 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.