Linktest Tutorial

Linktest is an online validation test of the network characteristics in an Emulab experiment. It's a check that Emulab set up the network as you requested. If you care about the fidelity of your network, you should set linktest to run on all or some swapins, and you should read this entire tutorial.

Contents


Quick Start

Temporarily, while we are validating and tuning linktest, on every swapin or modify:
(1) We ignore users' requests to set the linktest level below 3; i.e., we always run linktest, at level 3 or greater.
(2) Although the activity log still reports all linktest results, including failures, we email failures only to testbed-ops, not the user.
(If you explictly invoke linktest from the "Run Linktest" page or on ops, you get whatever level you request.)

To run linktest, select a Linktest test level from the dropdown on the Begin an Experiment page.

If you select a test level other than zero, Linktest will run after the experiment completes its swapin. If a problem is found, testbed-ops is automatically notified and a message will appear in the activation log. You will also receive an email message to ensure that you are aware of the problem. Otherwise, no notification will appear. A failure in linktest will not cause the swapin to fail! If traffic shaping parameters are of critical importance to your experiments, make sure you take a closer look if linktest reports failures!


Limitations (Important, Please Read)


Understanding Linktest

Linktest is an end-to-end validation test for Emulab experiments. It verifies that experiment nodes are up, that they are reachable by static routes (when applicable), and that traffic shaping on delay nodes matches the experiment NS script.

Linktest works by reading a data file of all of the links and their attributes, and then invoking external measurement tools -- namely ping, Rude and Crude and iperf. Linktest compares the results against margins of error calculated in advance to identify major errors in configuration.

Linktest runs on each experiment node. The Linktest daemon waits for a custom event instructing it to begin testing. When it receives the event, it invokes the Linktest script to conduct the actual tests. The script invokes external processes to validate links and log any errors found. If a node detects an error, it writes an explanatory message to the experiment tbdata/linktest directory. Otherwise, no messages appear in the directory after Linktest completes its run.

Linktest uses test levels to select which tests to perform. Test levels are cumulative, so that selecting a higher test level ensures lower-level tests are also run. Test levels are ordered in length of time to complete, so that Level 4 - Bandwidth takes the most time and Level 1 - Connectivity and Latency takes the least.

Read more about each test level in the following sections:


Advanced Topics

To run Linktest after experiment swapin, you may use Emulab's Web Interface, or you may manually invoke the script run_linktest.pl on ops. You may also examine Linktest output in its log directory. Read about these options in the following sections: