Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

This branch is 0 commits ahead and 0 commits behind master

Octocat-spinner-32 bin Cleanup all the source tree from dead code and cruft December 06, 2012
Octocat-spinner-32 data Add Makefile to fetch Maxmind geoip database files November 07, 2012
Octocat-spinner-32 decks Cleanup all the source tree from dead code and cruft December 06, 2012
Octocat-spinner-32 docs Fix #7936, minor typo in dnsspoof docs. January 11, 2013
Octocat-spinner-32 example_inputs Rename test_inputs to example_inputs November 29, 2012
Octocat-spinner-32 inputs Update the input README to be correct December 05, 2012
Octocat-spinner-32 nettests More consistent naming (dl is the deferred list l is the list) January 27, 2013
Octocat-spinner-32 ooni Remove unnecessary ooni imports (closes #8010) January 27, 2013
Octocat-spinner-32 oonib Add instructions for supervisord configuration and clean up README.md December 22, 2012
Octocat-spinner-32 scripts Update archive reports script to reflect report format changes January 27, 2013
Octocat-spinner-32 tests Disable some failing unittests in runner December 08, 2012
Octocat-spinner-32 var Cleanup all the source tree from dead code and cruft December 06, 2012
Octocat-spinner-32 .gitignore Apply patch from dma in #8009 #8008 February 04, 2013
Octocat-spinner-32 .gitmodules Updating the ooni/lib structure and git submodules for imports, and I… September 13, 2012
Octocat-spinner-32 AUTHORS Fix some docstrings November 10, 2012
Octocat-spinner-32 HACKING Merge branch 'timestamp' December 06, 2012
Octocat-spinner-32 LICENSE * Still squashing bugs. September 24, 2012
Octocat-spinner-32 Makefile * Minor change to Makefile. November 15, 2012
Octocat-spinner-32 README.md Add note on the versions of libdnet and pypcap (#7994) February 01, 2013
Octocat-spinner-32 TODO Do some cleaning up November 10, 2012
Octocat-spinner-32 fabfile.py Add fabfile for automatic deployment of ooni-probe to remote sites November 22, 2012
Octocat-spinner-32 ooniprobe.conf.sample Add ability to specify the Tor data directory from the config file January 27, 2013
Octocat-spinner-32 requirements.txt Strictly require Twisted 12.2.0. January 27, 2013
Octocat-spinner-32 setup.py Use saner variable names November 29, 2012
README.md

ooniprobe - Open Observatory of Network Interference

"The Net interprets censorship as damage and routes around it." - John Gilmore; TIME magazine (6 December 1993)

OONI, the Open Observatory of Network Interference, is a global observation network which aims is to collect high quality data using open methodologies, using Free and Open Source Software (FL/OSS) to share observations and data about the various types, methods, and amounts of network tampering in the world.

Let's get started with this already!

To run OONI-probe without having to install it you must tell python that it can import modules from the root of ooni-probe, as well as initialize the included submodules.

Getting started

Basic requirements:

On debian based systems these can be installed with:

sudo apt-get install git-core python python-pip python-dev build-essential

The python dependencies required for running ooniprobe are:

Install Tor

To get the latest version of Tor you should do the following (from: https://www.torproject.org/docs/debian):

# put in here the value of lsb_release -c (ex. oneirc for ubuntu 11.10 or squeeze for debian 6.0)
export DISTRIBUTION="squeeze"
echo "deb http://deb.torproject.org/torproject.org $DISTRIBUTION main" >> /etc/apt/sources.list
gpg --keyserver keys.gnupg.net --recv 886DDD89
gpg --export A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89 | sudo apt-key add -
apt-get update
apt-get install tor

Configurating a virtual environment

You are highly recommended to install python packages from inside of a virtual environment, since pip does not download the packages via SSL and you will need to install it system wide.

This will require you to have installed virtualenv.

sudo apt-get install python-virtualenv virtualenvwrapper

To create a new virtual environment do

mkdir $HOME/.virtualenvs
mkvirtualenv ooni-probe

You will automatically enter the environment. To re-enter this environment in the future, type:

workon ooni-probe

For convenience, you may want to add the following to your .bashrc:

if [ -e ~/ooni-probe/bin ]; then
    export PATH=~/ooni-probe/bin:$PATH
fi
if [ -e ~/ooni-probe ]; then
    export PYTHONPATH=$PYTHONPATH:~/ooni-probe
fi

Add the following to $HOME/.virtualenvs/ooni-probe/bin/postactivate to automatically cd into the working directory upon activation.

if [ -e ~/ooni-probe ] ; then
    cd ~/ooni-probe
fi

Installing ooni-probe

Clone the ooniprobe repository:

git clone https://git.torproject.org/ooni-probe.git
cd ooni-probe

Then install OONI with:

pip install -r requirements.txt

If you are not in a virtualenv you will have to run the above command as root:

sudo pip install -r requirements.txt

Install libdnet and pypcap python bindings

It's ideal to install these manually since the ones in debian or ubuntu are not up to date.

The version of pypcap and libdnet ooniprobe is current tested with are libdnet-1.12 and pypcap 1.1, any other version should be considered untested.

If you don't already have Subversion installed:

sudo apt-get install subversion

For libdnet:

wget https://libdnet.googlecode.com/files/libdnet-1.12.tgz
tar xzf libdnet-1.12.tgz
cd libdnet-1.12
./configure  && make
cd python/
python setup.py install
cd ../../ && rm -rf libdnet-1.12*

For pypcap:

git clone https://github.com/hellais/pypcap
cd pypcap/
pip install pyrex
make && make install
cd ../ && rm -rf pypcap-read-only

Including your geo data in the test report

Including geografical information on where your probe is located helps us better assess the value of the test. You can personalize these setting from inside of ooniprobe.conf

If you wish to include geografical data in the test report, you will have to go to the data/ directory and run:

make geoip

Then edit your ooniprobe.conf to point to the absolute path of where the data/ directory is located for example:

geoip_data_dir: /home/your_user/ooni-probe/data/

Running some tests

To see the possible command line options run:

./bin/ooniprobe --help 

For interesting tests to run look in the nettests/core/ directory.

To run a test you can do so with:

./bin/ooniprobe -o report_file_name path/to/test.py

Normally tests take options, you can see them with:

./bin/ooniprobe -o report_file_name path/to/test.py --help

Configuration

By default ooniprobe will not include personal identifying information in the test result, nor create a pcap file. This behavior can be personalized by editing your ooniprobe.conf configuration file.

Something went wrong with that request. Please try again.