|
|
@@ -0,0 +1,84 @@
|
|
|
+# Troll Patrol Artifact
|
|
|
+
|
|
|
+This repo contains scripts for reproducing the results in our paper.
|
|
|
+
|
|
|
+## Reproducing our results
|
|
|
+
|
|
|
+Dependencies:
|
|
|
+- bash
|
|
|
+- docker
|
|
|
+- git
|
|
|
+- numactl
|
|
|
+
|
|
|
+We use numactl to isolate each experiment to a single thread. If you do
|
|
|
+not want to install numactl, you can still run the script, but this may
|
|
|
+affect the results.
|
|
|
+
|
|
|
+To reproduce our results:
|
|
|
+
|
|
|
+1. `git clone -b artifact https://git-crysp.uwaterloo.ca/vvecna/lox-troll-patrol-extension`
|
|
|
+2. `cd lox-troll-patrol-extension`
|
|
|
+3. `./run.sh [-n NUM_PERFORMANCE_CORES]` or `./run-fast.sh [-n NUM_PERFORMANCE_CORES]`
|
|
|
+
|
|
|
+**The `./run.sh` script takes a long time and requires a few GB of free
|
|
|
+space.** The reason is that it downloads and processes all extra-info
|
|
|
+records for all bridges from 2020-07 to 2021-04 from the Tor Project's
|
|
|
+CollecTor service. This is about 4 million files, and it takes a long
|
|
|
+time to process them all. (These files are downloaded in compressed
|
|
|
+archives; the total download size for them is under 750 MB.)
|
|
|
+
|
|
|
+The `./run-fast.sh` script instead starts with a 6.7 MB archive (87 MB
|
|
|
+uncompressed) containing only the information we need. This is *much*
|
|
|
+faster and requires much less disk space. It yields identical results;
|
|
|
+however, it requires trusting that the pre-processed data was extracted
|
|
|
+correctly.
|
|
|
+
|
|
|
+See the "Time to Run" section below to estimate how long either option
|
|
|
+will take. The choice between the two scripts only determines whether
|
|
|
+`./scripts/belarus.sh` or `./scripts/belarus.sh --fast` will be run. The
|
|
|
+other steps are pretty quick. If you specify `-n NUM_PERFORMANCE_CORES`,
|
|
|
+then the Lox benchmarking step (`./scripts/generate-lox-results.sh`)
|
|
|
+will only use the first `NUM_PERFORMANCE_CORES` threads. This may take a
|
|
|
+bit longer but should ensure that the results are computed fairly.
|
|
|
+
|
|
|
+## Results
|
|
|
+
|
|
|
+The results are all output to the top-level directory of the project.
|
|
|
+After running either `./run.sh` or `./run-fast.sh`:
|
|
|
+- The results from Section 3 can be found in the **section-3-results** file.
|
|
|
+- Table 4 (found in Appendix A of the paper) can be found in **appendix-a-results.pdf**
|
|
|
+- Tables 2 and 3 (from Section 6) can be found in **table-2-results.pdf** and **table-3-results.pdf**.
|
|
|
+- Table 5 (in Appendix B) can be found in **appendix-b-results.pdf**.
|
|
|
+
|
|
|
+## Recovering from Errors
|
|
|
+
|
|
|
+Hopefully the script will just run everything without issue. If there is
|
|
|
+an issue at a step, try deleting the files/directories related to that
|
|
|
+step, stopping and removing any docker containers related to that step,
|
|
|
+and running the above script again. The script will not attempt to
|
|
|
+re-run steps that have files. If a step worked, just leave its files
|
|
|
+there, and you shouldn't have to redo that step.
|
|
|
+
|
|
|
+If you want to run the commands for individual steps, you can do that.
|
|
|
+From the top-level directory, run:
|
|
|
+- `./scripts/setup.sh` to clone dependencies and build the docker images
|
|
|
+- `./scripts/belarus.sh` to produce the results from Section 3 and Appendix A starting with all 20 GB of data from the Tor Project (or `./scripts/belarus.sh --fast` to start with some pre-processed data)
|
|
|
+- `./scripts/generate-lox-results.sh [-n NUM_EFFICIENT_CPUS]` to run the Lox benchmarking code to get the results from Section 6 and Appendix B (see the next step for producing the actual tables); specify `NUM_PERFORMANCE_CORES` to only use the first `NUM_PERFORMANCE_CORES` threads
|
|
|
+- `./scripts/process-lox-results.sh` to process the Lox benchmarking results previously produced by `./scripts/generate-lox-results.sh` and generate the tables in Section 6 and Appendix B
|
|
|
+
|
|
|
+## Time to Run
|
|
|
+
|
|
|
+On my laptop ([13th Gen Intel Core i7-1360P](https://www.intel.com/content/www/us/en/products/sku/232155/intel-core-i71360p-processor-18m-cache-up-to-5-00-ghz/specifications.html); 16 threads; 4 performance cores, up to 5 GHz):
|
|
|
+- `./scripts/setup.sh`: 10m 35s
|
|
|
+- `./scripts/belarus.sh`: 9h 15m 16s
|
|
|
+- `./scripts/belarus.sh --fast`: 1m 4s
|
|
|
+- `./scripts/generate-lox-results.sh -n 4`: 18m 39s
|
|
|
+- `./scripts/process-lox-results.sh`: 18s
|
|
|
+
|
|
|
+On the device used for the paper ([Intel Xeon Platinum 8380](https://www.intel.com/content/www/us/en/products/sku/212287/intel-xeon-platinum-8380-processor-60m-cache-2-30-ghz/specifications.html); 80 threads; 40 cores @ 2.30 GHz, up to 3.40 GHz):
|
|
|
+- `./scripts/setup.sh`: 6m 47s
|
|
|
+- `./scripts/belarus.sh`: 7h 57m 10s
|
|
|
+- `./scripts/belarus.sh --fast`: 1m 0s
|
|
|
+- `./scripts/generate-lox-results.sh`: 5m 56s
|
|
|
+- `./scripts/process-lox-results.sh`: 17s
|
|
|
+
|
