Pantheon of Congestion Control
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
.
Disclaimer
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.
Preparation
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
Dependencies
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 --install-deps
below.
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 <cc>
,
run 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.
Setup
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, src/experiments/setup.py
is
required to be run on every reboot (without --setup
).
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
Run 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.
Pantheon analysis
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 pantheon_report.pdf
.
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 src/wrappers/<cc>.py setup
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, test/setup.py
performs setup_after_reboot
by
default, and runs setup
on schemes when --setup
is given.
Next, execute the following command to find the running order for a scheme:
src/wrappers/<cc>.py run_first
Depending on the output of run_first
, run
# Receiver first
src/wrappers/<cc>.py receiver port
src/wrappers/<cc>.py sender IP port
or
# Sender first
src/wrappers/<cc>.py sender port
src/wrappers/<cc>.py receiver IP port
Run 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
pantheon
:git submodule add <your-cc-repo-url> third_party/<your-cc-repo-name>
and add
ignore = dirty
to.gitmodules
under your submodule. -
In
src/wrappers
, readexample.py
and 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.yml
along with settings ofname
,color
andmarker
, so thatsrc/experiments/test.py
is able to find your scheme andsrc/analysis/analyze.py
is able to plot your scheme with the specified settings. -
Add your scheme to
SCHEMES
in.travis.yml
for continuous integration testing. -
Send us a pull request and that's it, you're in the Pantheon!