See http://ucb-sts.github.com/sts/ for an HTML version of this file.
Ever had to manually dig through logs to find the one or two inputs that lead your controller software to break? STS seeks to eliminate this need, freeing you to debug the problematic code itself.
STS simulates the devices of your network, allowing you to programmatically generate tricky test cases, interactively examine the state of the network, and automatically find the exact inputs that are responsible for triggering a given bug.
STS depends on pox. To install STS, you'll just need to clone both repositories and load the hassel submodule:
$ git clone git://github.com/ucb-sts/sts.git
$ cd sts
$ git clone -b debugger git://github.com/ucb-sts/pox.git
$ ./tools/install_hassel_python.sh
For a detailed step-by-step walkthrough of STS's use cases, see this page.
For the impatient, take STS for a test drive with:
$ ./simulator.py
This will boot up pox, generate a simple 2-switch mesh topology, and begin feeding in random inputs.
You can also run STS interactively:
$ ./simulator.py -c config/interactive.py
STS can be used to replay previous executions:
# Assumes that ./simulator.py has been invoked.
$ ./simulator.py -c experiments/fuzz_pox_mesh/replay_config.py
Finally, STS is able to identify the minimal set of inputs that trigger a given bug:
# Assumes that ./simulator.py has been invoked, and terminated by finding an invariant violation.
$ ./simulator.py -c experiments/fuzz_pox_mesh/mcs_config.py
You can turn up the verbosity of the simulator's console output by passing the '-v' flag to simulator.py.
The simulator automatically copies your configuration parameters, event logs, and console output into the experiments/ directory for later examination.
The config/ directory contains sample configurations. You can specify your own config file by passing its path:
$ ./simulator.py -c config/my_config.py
See config/README for more information on how to write configuration files.
STS requires python 2.7+
To check network invariants with headerspace analysis, you will need to load hassel as a submodule and build it:
$ ./tools/install_hassel_python.sh
$ (cd sts/hassel/hassel-c && make -j)
Note that Hassel-C may not compile on Macintosh computers.
To use the advanced replay features of STS, you may need to install pytrie:
$ sudo pip install pytrie
The topology GUI depends on PyQt4.
For remote controllers, we use the paramiko ssh client:
$ sudo pip install paramiko
Interactive mode depends on the readline module:
$ sudo pip install readline
To enable checkpointing of controller state, you will need to install psutil:
$ sudo pip install psutil
Unit tests depends on the mock module:
$ sudo pip install mock
If your controller supports OpenFlow 1.0, STS works out of the box. You'll only need to change one line in the config file to instruct STS how to launch your controller process(es).
For a high-level overview of STS's software architecture, see this page.
For searchable code documentation, see this page.
For an overview of how to generate dataplane traffic in STS, see this page.
Check out this page.
For more information about the research behind STS, see our paper or our talk slides.
You should also check out our collection of replayable experiments that have been used to find and troubleshoot real bugs in SDN controllers:
$ git clone git://github.com/ucb-sts/experiments.git
Send questions or feedback to: sts-dev@googlegroups.com