To run linktest, select a Linktest test level from the dropdown on the Begin an Experiment page.
If you select a test lest level other than 0, 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. Otherwise, no notification will appear.
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 parsing the experiment NS script, then invoking external measurement tools -- namely ping, Rude and Crude and Pathrate. 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 parse the NS script, 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:
The default test level is Level 0 - Do not run Linktest. Use this level to leave Linktest turned off, performing no validation of experiment links after swapin.
Each Linktest node on a lan or direct link pings the node on the other side of the link. From the responses, the node detects whether the link is up and the latency of the link. Linktest compares the measured latency with the expected latency of the link, adjusting for known delay crossing the testbed backplane. If the measured latency is outside the 99% confidence interval for latencies at that setting, Linktest reports an error.
If the routing mode of the experiment is static, each Linktest node pings the remainder of nodes in the experiment. If any node cannot be reached, the Linktest node reports an error.
Each Linktest node on a lan or direct link with loss > 0 sends a burst of packets to the node on the other side of the link using Rude and Crude, a real-time packet emitter and collector. If the percentage of packets lost is outside the 99% confidence interval for normally-distributed loss at that setting, Linktest reports an error.
Each Linktest node on a lan or direct link uses Pathrate to measure the bandwidth of the link, provided that the link is >= 1 Mbps and <= 45 Mbps. If the measured bandwidth is outside the margin of error of 1Mb, Linktest reports an error.
The Bandwidth test adds up to 40 seconds per distinct link in the experiment, or 15-20 seconds in each direction. Linktest attempts to run tests in parallel whenever possible, but topologies such as a star will lead to longer runtimes because Linktest allows only one sender or receiver to run on a node at a time.
To run Linktest after experiment swapin, manually invoke the script run_linktest.pl on ops or use tevc to send a custom Linktest event. You may also examine Linktest output in its log directory. Read about these options in the following sections:
Use run_linktest.pl to run Linktest on ops. The option "-e" is mandatory for specifying the project and experiment id. Running with "-q" will run all tests except the bandwidth test. Running without "-q" runs all tests. Running with "-o" allows you to specify an output directory for log messages. Invoke run_linktest.pl with no options for a help message. Example:
run_linktest.pl -e utahstud/simple -q -o /tmp/linktest.log
You may also specify the test level using the "-l" option. Example:
run_linktest.pl -e utahstud/simple -l 1
After Linktest completes, run_linktest.pl prints out errors found during the run, if any. For scripting, run_linktest.pl returns 0 if no errors were found, or !0 if at least one error was found.
For the most fine-grained control of Linktest, use tevc to send Linktest events. Use STARTAT and STOPAT optional arguments to specify start and stop levels, or tevc to specify one test only. For example, to run only the bandwidth test:
tevc -e pid/eid now linktest start STARTAT=4 STOPAT=4
When running Linktest manually using tevc events, no messages appear indicating whether the tests passed. Instead, watch the contents of the tbdata/linktest directory for error reports.
Linktest logs the results of parsing the NS script and any error reports in the tbdata/linktest directory for each experiment. By default this is in ops:/proj/$pid/exp/$eid.