Installing ProtoGeni

The ProtoGENI software is currently under heavy development, but is already available for testing. Be aware that bugs do exist and that you will be helping us find them!

The following steps allow you to join the ProtoGENI federation.

1. Make sure you are running the latest GIT snapshot from the Utah repository. Instructions for accessing the GIT repository are in the Emulab wiki. Once you have a checkout, following the instructions for upgrading your boss.
2. If you already running Protogeni, then after you do your Emulab update, skip to Updating ProtoGeni section at the end of this document.
3. Install the libdnet port on your boss, as follows:

   cd /usr/ports/net/libdnet
   sudo make
   sudo make install
   

4. Once you are comfortable with the update process and you are sure your Emulab is still functioning (you can swap experiments in and out), you will want to do another rebuild on your boss node. First, add the following lines to your defs file:

   PROTOGENI_SUPPORT=1
   PROTOGENI_DOMAIN="mygeni"
   

   where mygeni should be changed to a short descriptive name for your installation. Once you have updated the configuration, compilation is performed as follows:

   cd /your/obj/dir
   /your/src/dir/configure --with-TBDEFS=/your/defs-default
   gmake
   sudo gmake boss-install
   cd protogeni
   gmake
   sudo gmake install
   

5. The remainder of the procedure is mostly automated: you should repeatedly invoke the following command:

   sudo /usr/testbed/sbin/protogeni/initsite
   

   and follow the instructions it provides as necessary. (Typically, you will need to join the ProtoGENI federation by sending your site key certificate to the Utah Emulab administrators; install a few more ports; and edit system configuration files such as /etc/rc.conf and /etc/crontab.)
6. Once initsite runs to completion, the site itself is ready.
7. Install and start the protogeni expiration daemon:

   cd /your/obj/dir/rc.d
   gmake
   sudo gmake install
   sudo /usr/testbed/sbin/protogeni/expire_daemon
   

   the daemon will background itself and return immediately, and will be automatically started when boss reboots.
8. If you want local resources to be registered with the clearinghouse (which is required to create slices which include resources handled by multiple component managers, for instance), then you need to run:

   /usr/testbed/sbin/protogeni/register_resources
   

   on boss.
9. Any user who wishes to access ProtoGENI resources should create a personal key. This is done through the WWW interface on your Emulab, by logging in, then following the My Emulab link in the upper left and then Generate SSL Cert on the far left. A secure passphrase must be supplied by the user.
10. A set of test scripts are available in the protogeni/test directory of your source tree. These scripts require the passphrase that the user chose in step 8 to be saved in $HOME/.ssl/password. Copy the entire directory over to your ops node. Start with the very simplest of the scripts, lookupuser.py, which will contact your new Slice Authority on boss and retrieve a credential, and then lookup the info the geniuser pseudo user. If this script fails, contact Utah.
11. Any user who has completed step 8 can now access ProtoGENI resources from your ops host. Use the test scripts mentioned in the previous step as a guide. Users must save the passphrase they chose in step 8 in $HOME/.ssl/password.
12. If you have any nodes that should not be used by ProtoGENI, then you should a row to the node_attributes table:

        mysql> insert into node_attributes values
                ('pcXXX', 'protogeni_exclude', 'Yep');
    

---

The current prototype is undergoing heavy development, so the above instructions are subject to change. Please send any comments to the developers.

Updating ProtoGeni

To update the Protogeni code, first follow the instructions in the upgrading Emulab wiki. Once that is done, you need to make sure that the new protogeni code is installed:

cd /your/obj/dir/protogeni
gmake
sudo gmake install

Then you need to apply any DB updates to the Protogeni databases:

cd /your/src/dir/protogeni/updates
sudo /usr/testbed/sbin/protogeni/update

Then restart the expiration daemon:

ps axuwww | grep expire_daemon
sudo kill <process number>
sudo /usr/testbed/sbin/protogeni/expire_daemon

And restart the SA daemon:

ps axuwww | grep sa_daemon
sudo kill <process number>
sudo /usr/testbed/sbin/protogeni/sa_daemon