OONI Probe: Installation guide

The Open Observatory of Network Interference (OONI) is a free software project under the Tor Project which aims to detect internet censorship, traffic manipulation and signs of surveillance around the world through the collection and processing of network measurements. Since late 2012, OONI has collected millions of network measurements across more than 100 countries around the world, shedding light on multiple cases of network interference.

OONI Probe is a program that users can run to probe their network and to collect data for the OONI project. Are you interested in testing your network for censorship and traffic manipulation? Do you want to collect data to share with others, so that you and others can better understand your network? If so, please read this document to learn how to install and run OONI Probe.

Risks of running OONI Probe

WARNING: Running OONI Probe carries risks.

In some countries, using active network measurement tools like OONI Probe may be illegal, or even considered espionage. Potential penalties and sanctions include imprisonment, physical assaults, large fines, threats, placement of government watch lists, and targeting for surveillance.

Some OONI Probe tests may connect to websites that are illegal in your country, and the tests themselves may violate your country’s computer misuse laws. OONI publishes all collected measurement data, which may include personally identifying information. Accordingly, sophisticated third parties, including internet service providers and website owners, may be able to detect your use of OONI Probe and report you to the authorities. We encourage you to consult with a lawyer licensed to practice in your jurisdiction prior to downloading and using OONI Probe.

Users run OONI Probe at their own risk. By installing OONI Probe, users agree to comply with OONI’s software license and Data Policy. Neither the OONI project nor its parent organization, The Tor Project, will be held liable, jointly or severally, at law or at equity, to OONI Probe users and other third parties for any risks or damages resulting from the use of OONI Probe under any tort, conract, or other causes of action.

Please read our relevant documentation to learn more about potential risks.

Installing OONI Probe

The desktop version of OONI Probe is currently designed for Linux and Mac OS X systems.

To install OONI Probe follow the steps below:

**On macOS** **Step 1.** Install **[homebrew](http://brew.sh)**. **Step 2.** Type the following in your terminal: ``` brew install OONI Probe ```
Please choose your linux version
**On Debian 8 "jessie":** **Step 1.** Configure the torproject repository by typing the following in your terminal: ``` curl https://deb.torproject.org/torproject.org/A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89.asc | gpg --import gpg --export A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89 | sudo apt-key add - echo 'deb http://deb.torproject.org/torproject.org jessie main' | sudo tee /etc/apt/sources.list.d/ooniprobe.list sudo apt-get update ``` **Step 2.** Type the following in your terminal: ``` sudo apt-get install ooniprobe deb.torproject.org-keyring ```
**On Debian 9 "stretch":** **Step 1.** Configure the torproject repository by typing the following in your terminal: ``` curl https://deb.torproject.org/torproject.org/A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89.asc | gpg --import gpg --export A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89 | sudo apt-key add - echo 'deb http://deb.torproject.org/torproject.org stretch main' | sudo tee /etc/apt/sources.list.d/ooniprobe.list sudo apt-get update ``` **Step 2.** Type the following in your terminal: ``` sudo apt-get install ooniprobe deb.torproject.org-keyring ```
**On Debian testing:** **Step 1.** Configure the torproject repository by typing the following in your terminal: ``` curl https://deb.torproject.org/torproject.org/A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89.asc | gpg --import gpg --export A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89 | sudo apt-key add - echo 'deb http://deb.torproject.org/torproject.org testing main' | sudo tee /etc/apt/sources.list.d/ooniprobe.list sudo apt-get update ``` **Step 2.** Type the following in your terminal: ``` sudo apt-get install ooniprobe deb.torproject.org-keyring ```
**On Debian unstable:** **Step 1.** Configure the torproject repository by typing the following in your terminal: ``` curl https://deb.torproject.org/torproject.org/A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89.asc | gpg --import gpg --export A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89 | sudo apt-key add - echo 'deb http://deb.torproject.org/torproject.org unstable main' | sudo tee /etc/apt/sources.list.d/ooniprobe.list sudo apt-get update ``` **Step 2.** Type the following in your terminal: ``` sudo apt-get install ooniprobe deb.torproject.org-keyring ```
**On Ubuntu 16.04 (xenial):** **Step 1.** Configure the torproject repository by typing the following in your terminal: ``` echo 'deb http://archive.ubuntu.com/ubuntu xenial universe' | sudo tee /etc/apt/sources.list.d/universe.list curl https://deb.torproject.org/torproject.org/A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89.asc | gpg --import gpg --export A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89 | sudo apt-key add - echo 'deb http://deb.torproject.org/torproject.org xenial main' | sudo tee /etc/apt/sources.list.d/ooniprobe.list sudo apt-get update ``` **Step 2.** Type the following in your terminal: ``` sudo apt-get install ooniprobe deb.torproject.org-keyring ```
**On Ubuntu 14.04 (trusty):** **Step 1.** Configure the torproject repository by typing the following in your terminal: ``` echo 'deb http://archive.ubuntu.com/ubuntu trusty universe' | sudo tee /etc/apt/sources.list.d/universe.list curl https://deb.torproject.org/torproject.org/A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89.asc | gpg --import gpg --export A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89 | sudo apt-key add - echo 'deb http://deb.torproject.org/torproject.org trusty main' | sudo tee /etc/apt/sources.list.d/ooniprobe.list sudo apt-get update ``` **Step 2.** Type the following in your terminal: ``` sudo apt-get install ooniprobe deb.torproject.org-keyring ```
**On other unix systems** Ensure that you have installed the following dependencies: * build-essential * python (>=2.7) * python-dev * pip * libgeoip-dev * libdumbnet-dev * libpcap-dev * libssl-dev * libffi-dev * tor (>=0.2.5.1 to run all the tor related tests) * virtualenv Then you can install OONI Probe inside a virtual environment with pip by typing the following in your terminal: ``` virtualenv env/ source env/bin/activate ``` To install the stable version: ``` pip install ooniprobe ``` To install from master: ``` pip install https://github.com/TheTorProject/ooni-probe/archive/master.zip ```
Your operating system is currently unsupported. You may want to try setting it up inside of a virtual machine.

Running OONI Probe

**On macOS** To collect measurements daily you should enable the service with: ``` brew services restart ooniprobe ``` You will then be able to access the web UI by opening in your web browser [http://localhost:8842](http://localhost:8842).
**On Debian/Ubuntu:** Access OONI Probe's web UI in you web's browser at [http://localhost:8842](http://localhost:8842) and go through the setup wizard process to initialize and use OONI Probe.
**On other unix systems** Type `OONI Probe-agent start` in your terminal to start OONI Probe agent. You should be presented with the following URL: [http://127.0.0.1:8842] (http://127.0.0.1:8842). By opening this URL [http://127.0.0.1:8842](http://127.0.0.1:8842) in your web browser you will be directed to OONI Probe's web UI setup wizard. Upon completion of the setup wizard process OONI Probe will be successfully initialized and ready to use. Further documentation on how to use OONI Probe's web UI can be found [here] (/post/web-ui-post/).
Your operating system is currently unsupported. You may want to try setting it up inside of a virtual machine.

Advanced users

Running OONI Probe from a virtual machine

You can run OONI Probe from a virtual machine through the following steps:

Step 1. Install Virtualbox (which is a prerequisite of Vagrant).

Step 2. Install Vagrant.

Step 3. Depending on your operating system, do the following:

Mac OS X

Install homebrew:

brew install git

Debian/Ubuntu

sudo apt-get install git

Step 4. Run the following from your terminal:

git clone https://github.com/TheTorProject/ooni-probe.git
cd ooni-probe/
vagrant up

Step 5. Access your virtual machine with:

vagrant ssh probe

Step 6. Start the OONI Probe agent:

ooniprobe-agent start

Step 7. Connect to the web UI on your host machine at: http://localhost:8842/

Setting capabilities on your virtualenv python binary

If your distribution supports capabilities you can avoid running OONI Probe as root through the following:

setcap cap_net_admin,cap_net_raw+eip /path/to/your/virtualenv's/python2

Running OONI Probe from a development environment

On Debian based systems a development environment can be setup as follows:

Step 1. Install all of the dependencies:

Step 2. Install OONI Probe in a virtual environment through the following:

git clone https://github.com/TheTorProject/ooni-probe
cd ooni-probe
virtualenv env

virtualenv venv will create a folder in the current directory which will contain the Python executable files, and a copy of the pip library which you can use to install other packages.

Step 3. Activate the virtual environment to begin using it, as follows:

source env/bin/activate
pip install -r requirements.txt
pip install -r requirements-dev.txt
python setup.py install
OONI Probe -s # if all went well, lists available tests

Running OONI Probe with Tor bridges

If Tor is blocked in the country that you are trying to run OONI Probe from, you can circumvent this censorship through the use of Tor bridges. OONI Probe will automatically try to use the bridges of Tor Browser but this requires that obfs4proxy is installed. You can do this through the following, depending on your operating system:

Mac OS X

Install Tor Browser and it will automatically find obfs4proxy.

Debian/Ubuntu

Install obfs4proxy:

sudo apt-get install obfs4proxy

You can also configure OONI Probe to use your own Tor bridges by editing the .ooni/ooniprobe.conf file in your home directory. Specifically, add the following in the torrc section and adjust them to your bridges:

tor:
    torrc:
       Bridge:
       - "obfs4 198.245.60.50:443 752CF7825B3B9EA6A98C83AC41F7099D67007EA5 cert=xpmQtKUqQ/6v5X7ijgYE/f03+l2/EuQ1dexjyUhh16wQlu/cpXUGalmhDIlhuiQPNEKmKw iat-mode=0"
       - "obfs4 154.35.22.10:41835 8FB9F4319E89E5C6223052AA525A192AFBC85D55 cert=GGGS1TX4R81m3r0HBl79wKy1OtPPNR2CZUIrHjkRg65Vc2VR8fOyo64f9kmT1UAFG7j0HQ iat-mode=0"
       ClientTransportPlugin: "obfs4 exec /usr/bin/obfs4proxy"