Logging Into the Web Interface
If you already have an account on the Testbed, all you need to do is go to Emulab Home Page, enter your login name and your password, and then click on the "Login" button. If you don't have an account, click on the "Join Project" or "Start Project" links. For an overiew of how you go about getting an Emulab account, go to the "How To Get Started" page.
Designing a Network Topology
The Testbed's power lies in its ability to assume many different topologies; the description of a such a topology is a necessary part of an experiment.
Emulab uses the "NS" ("Network Simulator") format to describe network topologies. This is substantially the same Tcl-based format used by ns-2. Since the Testbed offers emulation, rather than simulation, these files are interpreted in a somewhat different manner than ns-2. Therefore, some ns-2 functionality may work differently than you expect, or may not be implemented. If you feel there is useful functionality missing, please let us know. Also, some testbed-specific syntax has been added, which with the inclusion of compatibility module (tb_compat.tcl), will be ignored by the NS simulator. This allows the same NS file to work on both the Testbed and ns-2, most of the time.
For those unfamiliar with the NS format, here is a small example
(We urge all new Emulab users to begin with a small 3-5 node experiment
such as this, so that you will become familiar with NS syntax and the
practical aspects of Emulab operation). Let's say we are trying to
create a test network which looks like the following:
(A is connected to B, B to C, and B to D.)
An NS file which would describe such a topology is as follows. First
off, all NS files start with a simple prolog, declaring a simulator
and including a file that allow you to use the special
tb- commands:
# This is a simple ns script. Comments start with #.
set ns [new Simulator]
source tb_compat.tcl
Then define the 4 nodes in the topology.
set NodeA [$ns node]
set NodeB [$ns node]
set NodeC [$ns node]
set NodeD [$ns node]
Next define the 3 links between the nodes. NS syntax permits you to
specify the bandwidth, latency, and queue type. For our example, we
will define full speed links between B and C,D and a delayed link
from node A to B.
$ns duplex-link $NodeA $NodeB 100Mb 50ms DropTail
$ns duplex-link $NodeB $NodeC 100Mb .1ms DropTail
$ns duplex-link $NodeB $NodeD 100Mb .1ms DropTail
In addition to the standard NS syntax above, a number of
extensions have been added that allow you
to better control your experiment. For example, you may specify what
Operating System is booted on your nodes. We currently support FreeBSD
4.3 and Linux RedHat 7.1, as well as
OSKit kernels on the
testbed PCs. By default, Linux RedHat 7.1 is selected.
tb-set-node-os $NodeA FBSD-STD
tb-set-node-os $NodeC RHL-STD
You may also control what IP addresses are assigned to the
experimental interfaces on your nodes. The experiment configuration
software will select IP addresses for you, but if your experiment
depends on particular IP addresses, you may specify them at each
link. The following example sets the IP address of node B on the port
going to node C:
tb-set-ip-interface $NodeB $NodeC 192.168.42.42
Lastly, all NS files end with an epilog that instructs the simulator
to start.
# Go!
$ns run
If you would like to try the above example, the completed NS file can be run as an experiment in your project. Another example ns script that shows off using the power of Tcl to generate topologies is here.
Beginning the Experiment
After logging on to the Testbed Web Interface, choose the "Begin Experiment" option from the menu. First select which project you want the experiment to be configured in. Most people will be a member of just one project, and will not have a choice. If you are a member of multiple projects, be sure to select the correct project from the menu.
Next fill in the `Name' and `Long Name' fields. The Name should be a single word (no spaces) identifier, while the Long Name is a multi word description of your experiment. In the "Your NS file" field, place the local path of a NS file which you have created to describe your network topology. This file will be uploaded through your browser when you choose "Submit."
After submission, the Testbed interface will begin processing your request. This will likely take several minutes, depending on how large your topology is, and what other features (such as delay nodes and bandwidth limits) you are using. Assuming all goes well, you will receive an email message indicating success or failure, and if successful, a listing of the nodes and IP address that were allocated to your experiment.
For the NS file described above, you would receive a listing that looks
similar to this:
Node Mapping:
Virtual Physical Qualified Name
--------------- --------------- --------------------
nodeA pc12 nodeA.myproj.myexp.emulab.net
nodeB pc14 nodeB.myproj.myexp.emulab.net
nodeC pc16 nodeC.myproj.myexp.emulab.net
nodeD pc18 nodeD.myproj.myexp.emulab.net
delay0 pc7 delay0.myproj.myexp.emulab.net
IP Addresses:
Node IFC Destination IP
--------------- -------------------- --------------------
nodeB eth0 nodeC 192.168.42.42
nodeB eth2 nodeA 192.168.2.2
nodeA eth0 nodeB 192.168.2.3
nodeC eth0 nodeB 192.168.42.2
nodeD eth0 nodeB 192.168.3.2
nodeB eth1 nodeD 192.168.3.3
A few points should be noted:
- A single delay node was allocated and inserted into the link
between NodeA and NodeB. This link is invisible from your
perspective, except for the fact that it adds latency, error,
or reduced bandwidth.
- Delays of less than 3ms (per trip) are too small to be
accurately modeled at this time, and will be silently ignored.
Please see the
Link Loss Commands section in the
Extensions reference.
- The names in the "Qualified Name" column refer to the control
network interfaces for each of your allocated nodes. These names
are added to the Emulab nameserver map on the fly, and are
immediately available for you to use so that you do not have to
worry about the actual physical node names that were choosen. In
the names listed above, `myproj' is the name of the project that
you chose to work in, and `myexp' is the name of the experiment
that you provided in the "Begin Experiment" page.
- Since the IP address for the link from NodeB to NodeC was set in the NS file, the system selected an appropriate IP address for the other end of the link. All of the other links were configured by the system to use 192.168.XXX.XXX subnets.
Using your Nodes
By the time you receive the email message listing your nodes, the Testbed configuration system will have ensured that your nodes are fully configured and ready to use. If you have selected one of the Testbed supported operating system images (FreeBSD, Linux, NetBSD), this configuration process includes:
- loading fresh disk images so that each node is in a known clean state;
- rebooting each node so that it is running the OS specified in the NS script;
- configuring each of the network interfaces so that each one is "up" and talking to its virtual LAN (VLAN);
- creating user accounts for each of the project members;
- mounting the projects NFS directory in /proj so that project files are easily shared amongst all the nodes in the experiment;
- creating a /etc/hosts file on each node so that you may refer to the experimental interfaces of other nodes by name instead of IP number;
- configuring all of the delay parameters;
- configuring the tip lines so that project members may access the console ports from users.emulab.net.
As this point you may log into any of the nodes in your experiment. You will need to use Secure Shell (ssh), and you should use the `qualified name' from the nodes mapping table so that you do not form dependencies on any particular physical node. Your login name and password will be the same as your Web Interface login and password.
The /etc/hosts file on each node will provide a local name mapping for the other nodes in your experiments. You should take care to use these names (or IP numbers) and not the .emulab.net names listed in the node mapping, since the emulab names refer to the control network LAN that is shared amongst all nodes in all experiments. It is only the experimental interfaces that are entirely private to your experiment.
NOTE: The configuration process just described occurs only on Emulab constructed operating system images. If you are using an OSKit kernel, or your own disk image with your own operating system, you will be responsible for all of the configuration. At some point we hope to provide tools to assist in the configuration, but for now you are on your own.
I need root access!
If you need to customize the configuration, or perhaps reboot nodes,
you can use the "sudo" command, located in /usr/local/bin
on FreeBSD and Linux, and /usr/pkg/bin on NetBSD. Our
policy is very liberal; you can customize the configuration in any way
you like, provided it does not violate Emulab's
administrative policies. As as example, to reboot a node that is
running FreeBSD:
/usr/local/bin/sudo reboot
My node is wedged!
This is bound to happen when running experimental software and/or
experimental operating systems. Fortunately we have an easy way for
you to power cycle nodes without requiring Testbed Operations to get
involved. If you must power cycle a node, log on to users.emulab.net
and use the "node_reboot" command:
You may also reboot all the nodes in an experiment by using the -e
option to specify the project and experiment names. For example:
I've finished my experiment
When your experiment is completed, and you no longer need the resources that have been allocated to it, you will need to terminate the experiment via the Emulab Web Interface. Click on the "End An Experiment" link. You will be presented with a list of all of the experiments in all of the projects for which you have the authorization to terminate experiments. Select the experiment you want to terminate by clicking on the button in the "Terminate" column on the right hand side. You will be asked to confirm your choice. The Testbed configuration system will then tear down your experiment, and send you an email message when the process is complete. At this point you are allowed to reuse the experiment name (say, if you wanted to create a similar experiment with different parameters).