Masquerade experiements is a docker based test bed for proxies. It is foccused mainly on testing the proxy Masquerade but is designed to be modulable.
To run the experiement, you will need docker
and docker-compose
.
The experiement is also designed to run in background and need for that screen
To run the experiement, we use a Makefile, be careful, it may not react well to parallelised make, so be sure to run in serialized.
⚠️ The makefile makes use of a kill rule that remove all containers containingmasquerade_experiements
in their name, you may want to modify this rule to prevent killing unwanted containers.
By default, the images ares going to be build locally, this build can take up to an hour, you can chose to use publicly available version of the images on Docker Hub to do so, replace the occurance of the build
rule in the Makefile by the pull
rule.
The brosertime.env and basic_test.env files provide way of modifying the number of iterations of each test, they already have default value, also setting MESURE
to false will deactivate the browsertime test and respectivly the speedtest and bulkdownload test.
Moreover in the browsertime file, you can configure the country you are running on by setting COUNTRY
, possible values are DE
, FR
, IT
and US
, the default being IT
.
To run the experiement, just use the command make full
, or to run in detached mode make silent
.
This way of running the experiement will run the experiement following the script run.sh, you can modify it to choose which set of parameter to use.
To run the experiement in one particular condition, you can create a file network.env
and set the network conditions.
You can choose between setting
- the Upload, Download, RTT and Loss, setting the variable
UPLOAD
(in Mbps),DOWNLOAD
(in Mbps),RTT
(in ms) andLOSS
(in %), in this configurationUPLOAD
,RTT
andLOSS
are mandatory, if not set,DOWLOAD
will default toUPLOAD
; - the Technology, Quality, Operator and Country, setting the variable
TECHNOLOGY
,QUALITY
,OPERATOR
,COUNTRY
, andPERIODIC
(in sec), in this configuration onlyTECHNOLOGY
is mandatory, the others will default touniversal
andPERIODIC
will default to 10sec; this configuration uses ERRANT to enforce the trafic shapping, please refer to their README.md for more information about valid parameters.
Once the network.env
file is set, you just need to use the command make run
The Makefile provides a make clean
commands that will make sure that any running containers corresponding to the experiement are stopped and prune all container, images, volumes and network.
⚠️ This can cause the loss of unwanted datas
All the results of the experiement are stored in the results
folder.
You can use the command make full_compile
to create plots about the experiements you just run, the plot will be found in the results/results/
subfolders.
You can also choose to use the YAML files found in results/results
to run them with Masquerade Data Analysis to an analyse of the results.
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
To add a test, you need to:
- create the corresponding python class in
results-compilation
to represent the test's result, it can inherite the classResult
for simplicity purpose; - create an Docker image to run the test;
- add the build recipe to the
docker-compose-build.yml
file; - add the run recipe to the
docker-compose-measure.yml
file, make sure it runs before thebulk_download
container and after one of the previous test finished.
To add a new metric, you will need to:
- create the corresponding test if need be;
- add the support in the test-corresponding python class in
results-compilation
.
To add a setup, you will need to:
- modify the classes in
results-compilation
by adding a new field for this scenario and modify all subsequent class et method; - modify the
entrypoint.sh
of all the test for them to test also your new setup; - create the Docker images nedeed;
- add their build recipes to the
docker-compose-build.yml
file; - add their run recipes to the
docker-compose-measure.yml
file, make sure they are started before the run of the first test.
The project already contains a pre-commit-config, to install the necessary dependencies, run pip install -Ur pre-commit-requirements.txt
But is not working properly because some images need python >=3.7 <3.10 while other need python >=3.10
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.