commit 3c010b702f8ddfdcd95ff7b0cd9137376255b4f4 Author: Arturo Filastò <art@fuffa.org> Date: Tue Aug 19 11:03:51 2014 +0200 Reformat README.md so that it uses syntax common to markdown and rst. --- README.md | 231 +++++++++++++++++++++++++++++++------------------------------ 1 file changed, 117 insertions(+), 114 deletions(-) diff --git a/README.md b/README.md index 28c895c..ce7ba6e 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,8 @@ with others, so that you and others may better understand your network? If so, please read this document and we hope ooniprobe will help you to gather network data that will assist you with your endeavors! -#### Read this before running ooniprobe! +Read this before running ooniprobe! +----------------------------------- Running ooniprobe is a potentially risky activity. This greatly depends on the jurisdiction in which you are in and which test you are running. It is @@ -32,41 +33,43 @@ Futhermore, ooniprobe takes no precautions to protect the install target machine from forensics analysis. If the fact that you have installed or used ooni probe is a liability for you, please be aware of this risk. -## Installation +Installation +============ -### Debian based systems +Debian based systems +-------------------- -``` -sudo sh -c 'echo "deb http://deb.ooni.nu/ooni wheezy main" >> /etc/apt/sources.list' -gpg --keyserver pgp.mit.edu --recv-key 0x49B8CDF4 -gpg --export 89AB86D4788F3785FE9EDA31F9E2D9B049B8CDF4 | sudo apt-key add - -sudo apt-get update && sudo apt-get install ooniprobe -``` +Run this:: -### Linux + sudo sh -c 'echo "deb http://deb.ooni.nu/ooni wheezy main" >> /etc/apt/sources.list' + gpg --keyserver pgp.mit.edu --recv-key 0x49B8CDF4 + gpg --export 89AB86D4788F3785FE9EDA31F9E2D9B049B8CDF4 | sudo apt-key add - + sudo apt-get update && sudo apt-get install ooniprobe + +Linux +----- We believe that ooniprobe runs reasonably well on Debian GNU/Linux wheezy as well as versions of Ubuntu such as natty and later releases. Running ooniprobe -without installing it is supported with the following commands: +without installing it is supported with the following commands:: + + git clone https://git.torproject.org/ooni-probe.git + cd ooni-probe + ./setup-dependencies.sh + python setup.py install -``` -git clone https://git.torproject.org/ooni-probe.git -cd ooni-probe -./setup-dependencies.sh -python setup.py install -``` +Setting up development environment +---------------------------------- -### Setting up development environment +On debian based systems this can be done with:: -On debian based systems this can be done with: -``` -sudo apt-get install libgeoip-dev python-virtualenv virtualenvwrapper -mkvirtualenv ooniprobe -python setup.py install -pip install -r requirements-dev.txt -``` + sudo apt-get install libgeoip-dev python-virtualenv virtualenvwrapper + mkvirtualenv ooniprobe + python setup.py install + pip install -r requirements-dev.txt -### Other platforms (with Vagrant) +Other platforms (with Vagrant) +------------------------------ 0) [Install Vagrant](https://www.vagrantup.com/downloads.html) and [Install Virtualbox](https://www.virtualbox.org/wiki/Downloads) @@ -74,41 +77,32 @@ pip install -r requirements-dev.txt On OSX: -If you don't have it install homebrew http://mxcl.github.io/homebrew/ +If you don't have it install homebrew http://mxcl.github.io/homebrew/:: -``` -brew install git -``` + brew install git -On debian/ubuntu: +On debian/ubuntu:: -``` -sudo apt-get install git -``` + sudo apt-get install git -1) Open a Terminal and run: +1) Open a Terminal and run:: -``` -git clone https://git.torproject.org/ooni-probe.git -cd ooni-probe/ -vagrant up -``` + git clone https://git.torproject.org/ooni-probe.git + cd ooni-probe/ + vagrant up -2) Login to the box with: +2) Login to the box with:: -``` -vagrant ssh -``` + vagrant ssh -ooniprobe will be installed in `/ooni`. +ooniprobe will be installed in ``/ooni``. -3) You can run tests with: +3) You can run tests with:: -``` -ooniprobe blocking/http_requests -f /ooni/example_inputs/alexa-top-1k.txt -``` + ooniprobe blocking/http_requests -f /ooni/example_inputs/alexa-top-1k.txt -## Using ooniprobe +Using ooniprobe +=============== **Net test** is a set of measurements to assess what kind of internet censorship is occurring. @@ -123,87 +117,85 @@ ooniprobe blocking/http_requests -f /ooni/example_inputs/alexa-top-1k.txt ### Configuring ooniprobe You may edit the configuration for ooniprobe by editing the configuration file -found inside of `~/.ooni/ooniprobe.conf`. +found inside of ``~/.ooni/ooniprobe.conf``. By default ooniprobe will not include personal identifying information in the test result, nor create a pcap file. This behavior can be personalized. -### Running decks +Running decks +------------- + +You will find all the installed decks inside of ``/usr/share/ooni/decks``. + +You may then run a deck by using the command line option ``-i``: + +As root:: -You will find all the installed decks inside of `/usr/share/ooni/decks`. + ooniprobe -i /usr/share/ooni/decks/mlab.deck -You may then run a deck by using the command line option `-i`: -As root: -``` -ooniprobe -i /usr/share/ooni/decks/mlab.deck -``` +Or as a user:: + + ooniprobe -i /usr/share/ooni/decks/mlab_no_root.deck -Or as a user: -``` -ooniprobe -i /usr/share/ooni/decks/mlab_no_root.deck -``` Or: -As root: -``` -ooniprobe -i /usr/share/ooni/decks/complete.deck -``` +As root:: + + ooniprobe -i /usr/share/ooni/decks/complete.deck + + +Or as a user:: + + ooniprobe -i /usr/share/ooni/decks/complete_no_root.deck -Or as a user: -``` -ooniprobe -i /usr/share/ooni/decks/complete_no_root.deck -``` The above tests will require around 20-30 minutes to complete depending on your network speed. If you would prefer to run some faster tests you should run: -As root: -``` -ooniprobe -i /usr/share/ooni/decks/fast.deck -``` +As root:: + + ooniprobe -i /usr/share/ooni/decks/fast.deck + + +Or as a user:: + + ooniprobe -i /usr/share/ooni/decks/fast_no_root.deck + + +Running net tests +----------------- + +You may list all the installed stable net tests with:: + -Or as a user: -``` -ooniprobe -i /usr/share/ooni/decks/fast_no_root.deck -``` + ooniprobe -s -### Running net tests -You may list all the installed stable net tests with: +You may then run a nettest by specifying its name for example:: -``` -ooniprobe -s -``` -You may then run a nettest by specifying its name for example: + ooniprobe manipulation/http_header_field_manipulation -``` -ooniprobe manipulation/http_header_field_manipulation -``` -It is also possible to specify inputs to tests as URLs: +It is also possible to specify inputs to tests as URLs:: + + + ooniprobe blocking/http_requests -f httpo://ihiderha53f36lsd.onion/input/37e60e13536f6afe47a830bfb6b371b5cf65da66d7ad65137344679b24fdccd1 -``` -ooniprobe blocking/http_requests -f httpo://ihiderha53f36lsd.onion/input/37e60e13536f6afe47a830bfb6b371b5cf65da66d7ad65137344679b24fdccd1 -``` You can find the result of the test in your current working directory. By default the report result will be collected by the default ooni collector and the addresses of test helpers will be obtained from the default bouncer. -You may also specify your own collector or bouncer with the options `-c` and -`-b`. +You may also specify your own collector or bouncer with the options ``-c`` and +``-b``. -## (Optional) Install obfsproxy -Install the latest version of obfsproxy for your platform. - -[Download Obfsproxy](https://www.torproject.org/projects/obfsproxy.html.en) - -## Bridges and obfsproxy bridges +Bridges and obfsproxy bridges +============================= ooniprobe submits reports to oonib report collectors through Tor to a hidden service endpoint. By default, ooniprobe uses the installed system Tor, but can @@ -215,16 +207,25 @@ used in torrc, and as returned by https://bridges.torproject.org). If obfsproxy bridges are to be used, the path to the obfsproxy binary must be configured. See option advanced.obfsproxy_binary, in ooniprobe.conf. -## Setting capabilities on your virtualenv python binary +(Optional) Install obfsproxy +---------------------------- + +Install the latest version of obfsproxy for your platform. -If your distributation supports capabilities you can avoid needing to run OONI as root: +[Download Obfsproxy](https://www.torproject.org/projects/obfsproxy.html.en) -``` -setcap cap_net_admin,cap_net_raw+eip /path/to/your/virtualenv's/python -``` +Setting capabilities on your virtualenv python binary +===================================================== +If your distributation supports capabilities you can avoid needing to run OONI as root:: -## Reporting bugs + + setcap cap_net_admin,cap_net_raw+eip /path/to/your/virtualenv's/python + + + +Reporting bugs +============== You can report bugs and issues you find with ooni-probe on The Tor Projec issue tracker [filing them under the "Ooni" component](https://trac.torproject.org/projects/tor/newticket?component=Ooni). @@ -232,13 +233,14 @@ tracker [filing them under the "Ooni" component](https://trac.torproject.org/pro You can either register an account or use the group account "cypherpunks" with password "writecode". -## Contributing +Contributing +============ -You can download the code for ooniprobe from the following git repository: +You can download the code for ooniprobe from the following git repository:: + + + git clone https://git.torproject.org/ooni-probe.git -``` -git clone https://git.torproject.org/ooni-probe.git -``` It is also viewable on the web via [https://gitweb.torproject.org/ooni-probe.git](https://git.torproject.org/ooni-probe.git). @@ -251,8 +253,9 @@ Read this article to learn how to [create a pull request on github](https://help If you prefer not to use github (or don't have an account), you may also submit patches as attachments to tickets. -Be sure to format the patch (given that you are working on a feature branch that is different from master) with: +Be sure to format the patch (given that you are working on a feature branch +that is different from master) with:: + + + git format-patch master --stdout > my_first_ooniprobe.patch -``` -git format-patch master --stdout > my_first_ooniprobe.patch -```