tornettools is a utility to guide you through the Tor network experimentation process using Shadow, by assisting with the following experimentation steps:
- stage: Process Tor metrics data for staging network generation
- generate: Generate TorNet network configurations
- simulate: Run a TorNet simulation in Shadow
- parse: Parse useful data from simulation log files
- plot: Plot previously parsed data to visualize results
- archive: Cleanup and compress Shadow simulation data
The configuration files that are generated can be run in the Shadow network simulator; NetMirage and Chutney may eventually support the files generated with this tool.
The generated networks include the use of TGen for the generation of realistic background traffic, and OnionTrace for the collection of information from Tor throughout an experiment.
This tool was initially created as part of the following research publication. Please cite this paper if you use this tool in your work:
Once is Never Enough: Foundations for Sound Statistical Inference in Tor Network Experimentation
Proceedings of the 30th USENIX Security Symposium (Sec 2021)
by Rob Jansen, Justin Tracey, and Ian Goldberg
Here is a bibtex entry for latex users:
@inproceedings{neverenough-sec2021,
author = {Rob Jansen and Justin Tracey and Ian Goldberg},
title = {Once is Never Enough: Foundations for Sound Statistical Inference in {Tor} Network Experimentation},
booktitle = {30th USENIX Security Symposium (Sec)},
year = {2021},
note = {See also \url{https://neverenough-sec2021.github.io}},
}
Development of tornettools is slow and typically focuses on changes that keep the tool in sync with changes being made in Shadow. Thus, you should generally just ignore the tornettools version numbers and use the latest version. Sometimes you might want to pin to a specific version that is known to be compatible with your version of Shadow, e.g., when building container images, and in this case we recommend pinning to a specific commit hash.
We do use version numbers, but they have historically been based on vibes rather than semver and we don't want to introduce the overhead of following a more strict policy than that.
python3 -m venv toolsenv
source toolsenv/bin/activate
pip install -r requirements.txt
# if you plan to make changes to tornettools, you can add the '--editable' pip install flag
# to avoid the need to re-run 'pip install' after every modification:
# https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs
pip install --ignore-installed .
tornettools -h
tornettools stage -h
tornettools generate -h
tornettools simulate -h
tornettools parse -h
tornettools plot -h
tornettools archive -h
wget https://collector.torproject.org/archive/relay-descriptors/consensuses/consensuses-2023-04.tar.xz
wget https://collector.torproject.org/archive/relay-descriptors/server-descriptors/server-descriptors-2023-04.tar.xz
wget https://metrics.torproject.org/userstats-relay-country.csv
wget https://collector.torproject.org/archive/onionperf/onionperf-2023-04.tar.xz
wget -O bandwidth-2023-04.csv "https://metrics.torproject.org/bandwidth.csv?start=2023-04-01&end=2023-04-30"
tar xaf consensuses-2023-04.tar.xz
tar xaf server-descriptors-2023-04.tar.xz
tar xaf onionperf-2023-04.tar.xz
git clone https://github.com/tmodel-ccs2018/tmodel-ccs2018.github.io.git
sudo apt-get install openssl libssl-dev libevent-dev build-essential automake zlib1g zlib1g-dev
git clone https://git.torproject.org/tor.git
cd tor
./autogen.sh
./configure --disable-asciidoc --disable-unittests --disable-manpage --disable-html-manual
make -j$(nproc)
cd ..
tornettools
also uses the faketime
, dstat
, free
, and xz
command-line
tools. On Ubuntu these can be installed with:
sudo apt-get install faketime dstat procps xz-utils
export PATH=${PATH}:`pwd`/tor/src/core/or:`pwd`/tor/src/app:`pwd`/tor/src/tools
tornettools stage \
consensuses-2023-04 \
server-descriptors-2023-04 \
userstats-relay-country.csv \
tmodel-ccs2018.github.io \
--onionperf_data_path onionperf-2023-04 \
--bandwidth_data_path bandwidth-2023-04.csv \
--geoip_path tor/src/config/geoip
For example, use --network_scale 0.01
to generate a private Tor network at '1%' the scale of public Tor:
tornettools generate \
relayinfo_staging_2023-04-01--2023-04-30.json \
userinfo_staging_2023-04-01--2023-04-30.json \
networkinfo_staging.gml \
tmodel-ccs2018.github.io \
--network_scale 0.01 \
--prefix tornet-0.01
Make sure you have already installed shadow, tgen, and oniontrace.
Note that simulating a '1%' Tor network for 60 simulation minutes can take as much as 30GiB of RAM.
tornettools simulate tornet-0.01
tornettools parse tornet-0.01
tornettools plot \
tornet-0.01 \
--tor_metrics_path tor_metrics_2023-04-01--2023-04-30.json \
--prefix pdfs
tornettools archive tornet-0.01
Performance metrics are plotted in the graph files in the pdfs directory.