Emulab Tutorial

Contents


Getting Started

This section of the tutorial describes how to run your first Emulab experiment. We cover basic NS syntax and various operational issues that you will need to know in order conduct experiments to completion. Later sections of the tutorial will cover more advanced topics such as loading your own RPMs automatically, running programs automatically, running batch jobs, creating your own disk images and loading those images on your nodes. For your convenience, there is also a Java GUI interface you can use to create NS files for your experiments.


Advanced Topics


Batch Mode


Custom OS Images

If your set of operating system customizations cannot be easily contained within an RPM/TAR (or multiple RPM/TARs), then you can create your own custom OS image; Emulab allows you to create your own disk images and load them on your experimental nodes, automatically when your experiment is created or swapped in. Once you have created a custom disk image (and the associated image/osid descriptor for it, you can use that OSID in your NS file. When your experiment is swapped in, the testbed system will arrange for your disks to be loaded in parallel using a locally written multicast disk loading protocol. Experience has shown that it is much faster to load a disk image on 10 nodes at once, then it is to load a bunch of RPMS or tarballs on each node as it boots. So, while it may seem like overkill to create your own disk image, we can assure you it is not!

The most common approach is to use the New Image Descriptor form to create a disk image that contains a customized version of the standard Redhat Linux partition or the FreeBSD partition. Or, you can start from scratch and load your own operating system in any of the DOS partitions, and then capture that partition when you are done. Either way, all you need to do is enter the node name in the form, and the testbed system will create the image for you automatically, notifying you via email when it is finished. You can then use that image in subsequent experiments by specifying the descriptor name in your NS file with the tb-set-node-os directive. When the experiment is configured, the proper image will be loaded on each node automatically by the Emulab system.

A typical approach to creating your own disk image using one of the default images as a base, goes like this:

  1. Create a single-node Linux or FreeBSD experiment. In your NS file, use the appropriate tb-set-node-os directive. For example, one of the following statements:
         tb-set-node-os $NodeA FBSD-STD
         tb-set-node-os $NodeA RHL-STD		
  2. After your experiment has swapped in (you have received the email saying it is running), log into the node and load all of the RPMS and software packages that you wish to load. Be sure to arrange for any programs that need to be started at boot time. It is a good idea to reboot the node and make sure that everything is running as you want it to when it comes up.
  3. Note the physical (pcXX) name of the machine used!
  4. Create an image descriptor and image using the New Image Descriptor form. For "which DOS partition" select 1 if you are customizing the FreeBSD slice, or 2 if you are customizing the Linux slice. Since you are customizing one of the base images, you should select all four OS features, operational mode "NormalV1", and all four node types (pc600, etc.). Leave the last two check boxes alone.

    Where it asks for "Node to Create Image from," fill in the node you have just customized ((pcXX noted in previous step). Then click the submit button.
  5. Wait for the email saying the image creation is done.
  6. Now you can create a second single-node experiment to test your new image. In your .ns file, use tb-set-node-os to select the OSID that you just created. Be sure to remove any RPM or tarball directives. Submit that NS file and wait for the email notification. Then log into the new node and check to make sure everything is running normally.
  7. If everything is going well, terminate both of these single-node experiments. If not, release the experiment created in the previous step, and then go back and fix the original node (pcXX above). Recreate the image as needed:
         create_image -p <pid> <imageid> <node>  
  8. Once your image is working properly, you can use it in any NS file by using the tb-set-node-os.
If you ever want to reload a node in your experiment, either with one of your images or with one of the default images, you can use the os_load command. Log into users and run:
	os_load -p <pid> -i <imageid> <node> 
This program will run in the foreground, waiting until the image has been loaded. At that point you should log in and make sure everything is working oaky. You might want to watch the console line as well (see the FAQ). If you want to load the default image, then simply run:
	os_load <node>