The Pantheon contains wrappers for many popular practical and research congestion control schemes. The Pantheon enables them to run on a common interface, and has tools to benchmark and compare their performances. Pantheon tests can be run locally over emulated links using mahimahi or over the Internet to a remote machine.
Our website is https://pantheon.stanford.edu, where you can find more information about Pantheon, including supported schemes, measurement results on a global testbed so far, and our paper at USENIX ATC 2018 (Awarded Best Paper). In case you are interested, the scripts and traces (including "calibrated emulators") for running the testbed can be found in observatory.
To discuss and talk about Pantheon-related topics and issues, feel free to
post in the Google Group
or send an email to
pantheon-stanford <at> googlegroups <dot> com.
This is research software. Our scripts will write to the file system in the
pantheon folder. We never run third party programs as root, but we cannot
guarantee they will never try to escalate privilege to root.
You might want to install dependencies and run the setup on your own, because our handy scripts will install packages and perform some system-wide settings (e.g., enabling IP forwarding, loading kernel modeuls) as root. Please run at your own risk.
To clone this repository, run:
git clone https://github.com/StanfordSNR/pantheon.git
Many of the tools and programs run by the Pantheon are git submodules in the
third_party folder. To add submodules after cloning, run:
git submodule update --init --recursive # or tools/fetch_submodules.sh
We provide a handy script
tools/install_deps.sh to install globally required
dependencies; these dependencies are required before testing any scheme
and are different from the flag
In particular, we created the Pantheon-tunnel
that is required to instrument each scheme.
You might want to inspect the contents of
install_deps.sh and install these dependencies by yourself in case you want to
manage dependencies differently. Please note that Pantheon currently
only supports Python 2.7.
Next, for those dependencies required by each congestion control scheme
src/wrappers/<cc>.py deps to print a dependency list. You could install
them by yourself, or run
src/experiments/setup.py --install-deps (--all | --schemes "<cc1> <cc2> ...")
to install dependencies required by all schemes or a list of schemes separated by spaces.
After installing dependencies, run
src/experiments/setup.py [--setup] [--all | --schemes "<cc1> <cc2> ..."]
to set up supported congestion control schemes.
--setup is required
to be run only once. In contrast,
required to be run on every reboot (without
Running the Pantheon
To test schemes in emulated networks locally, run
src/experiments/test.py local (--all | --schemes "<cc1> <cc2> ...")
To test schemes over the Internet to remote machine, run
src/experiments/test.py remote (--all | --schemes "<cc1> <cc2> ...") HOST:PANTHEON-DIR
src/experiments/test.py local -h and
src/experiments/test.py remote -h
for detailed usage and additional optional arguments, such as multiple flows,
running time, arbitrary set of mahimahi shells for emulation tests,
data sender side for real tests; use
--data-dir DIR to specify an
an output directory to save logs.
To analyze test results, run
src/analysis/analyze.py --data-dir DIR
It will analyze the logs saved by
src/experiments/test.py, then generate
performance figures and a full PDF report
Running a single congestion control scheme
All the available schemes can be found in
src/config.yml. To run a single
congestion control scheme, first follow the Dependencies section to install
the required dependencies.
At the first time of running, run
to perform the persistent setup across reboots, such as compilation,
generating or downloading files to send, etc. Then run
src/wrappers/<cc>.py setup_after_reboot, which also has to be run on every
reboot. In fact,
default, and runs
setup on schemes when
--setup is given.
Next, execute the following command to find the running order for a scheme:
Depending on the output of
# Receiver first src/wrappers/<cc>.py receiver port src/wrappers/<cc>.py sender IP port
# Sender first src/wrappers/<cc>.py sender port src/wrappers/<cc>.py receiver IP port
src/wrappers/<cc>.py -h for detailed usage.
How to add your own congestion control
Adding your own congestion control to Pantheon is easy! Just follow these steps:
Fork this repository.
Add your congestion control repository as a submodule to
git submodule add <your-cc-repo-url> third_party/<your-cc-repo-name>
ignore = dirtyto
.gitmodulesunder your submodule.
example.pyand create your own
<your-cc-name>.py. Make sure the sender and receiver run longer than 60 seconds; you could also leave them running forever without the need to kill them.
Add your scheme to
src/config.ymlalong with settings of
marker, so that
src/experiments/test.pyis able to find your scheme and
src/analysis/analyze.pyis able to plot your scheme with the specified settings.
Add your scheme to
.travis.ymlfor continuous integration testing.
Send us a pull request and that's it, you're in the Pantheon!