[tor-commits] [oonib/master] Updated the README with better instructions. [ci skip]
isis at torproject.org
isis at torproject.org
Sat May 4 16:10:28 UTC 2013
commit d67644556149f183850e81c8dfc74e04498f219b
Author: Isis Lovecruft <isis at torproject.org>
Date: Sun Apr 21 10:30:38 2013 +0000
Updated the README with better instructions. [ci skip]
---
README.md | 113 ++++++++++++++++++++++++++++++++++++------------------------
1 files changed, 68 insertions(+), 45 deletions(-)
diff --git a/README.md b/README.md
index f176bb4..90a3d1a 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,52 @@
# Dependencies and Installation
+ - cp oonib.conf.example oonib.conf
+ - chmod +x .travis.test.sh && ./.travis.test.sh 30 ./bin/oonib
+ - echo "Build successful."
-We recommend that you use a python virtualenv. The recommended commands for
-setting up an ooni-backend are:
+## Distro dependencies (Debian)
+There are a few dependencies which we recommend you get from your
+distribution's archives.
+
+ sudo apt-get install build-essential python-dev python-setuptools openssl
+
+### Tor
+You will need a Tor binary on your system. For complete instructions, see also:
- sudo apt-get install build-essential python-dev python-setuptools
- # Grab the get-pip installer to make sure we have pip>=1.3.0 [1]
+ https://www.torproject.org/docs/tor-doc-unix.html.en
+ https://www.torproject.org/docs/rpms.html.en
+
+If you've already got Tor, or plan to compile it yourself from source, great!
+You can skip this step. Otherwise, if you're installing Tor (or reinstalling),
+you'll want to make sure to get our keyring package in Debian:
+
+ echo "deb http://deb.torproject.org/torproject.org wheezy main" | \
+ sudo tee -a /etc/apt/sources.list
+ gpg --keyserver keys.gnupg.net --recv 886DDD89
+ gpg --export A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89 | sudo apt-key add -
+ sudo apt-get update
+ sudo apt-get install deb.torproject.org-keyring tor tor-geoipdb
+
+### Pip (>=1.3.0)
+We recommend using the Pip>=1.3.0 because it included several important
+security and privacy related patches:
+
+ * It forces the use of HTTPS for [PyPI](pypi.python.org).
+ * and checks package hash sums before installation, with support for hashes
+ more collision-resistant than MD5.
+
+The least painful way (that we know of) to install a newer Pip is to use Pip's
+get-pip script:
+
+ # Grab the get-pip installer to make sure we have pip>=1.3.0
curl -O https://raw.github.com/pypa/pip/master/contrib/get-pip.py
sudo python ./get-pip.py ## pip (>=1.3.0) is recommended for security reasons
+ # And make sure we're actually using the newer one:
sudo update-alternatives --install /usr/bin/pip pip /usr/local/bin/pip 0
+
+### Virtualenv
+We recommend that you use a python virtualenv. The recommended commands for
+setting up this up and installing are:
+
sudo pip install --upgrade virtualenv virtualenvwrapper
# Setup the virtualenv directory:
export WORKON_HOME=~/.virtualenvs && mkdir -p $WORKON_HOME
@@ -15,16 +54,28 @@ setting up an ooni-backend are:
# Clone ooni-backend:
git clone https://github.com/TheTorProject/ooni-backend.git && cd ooni-backend
# Create the virtualenv for ooni-backend...
- mkvirtualenv -a $PWD -r requirements.txt --unzip-setuptools --setuptools --no-site-packages oonib
+ mkvirtualenv -a $PWD --unzip-setuptools --setuptools --no-site-packages oonib
# ...and install ooni-backend (sudo is not necessary since we're in a virtualenv):
+ pip install -r requirements.txt --use-mirrors
python setup.py install
-[1] Note: pip>=1.3.0 is recommended because it included several security
- patches, including using forcing the use of HTTPS and checking package hash
- sums before installation.
+# Running an OONI collector
+
+## Configure oonib
-# Generate self signed certs for OONIB
+Copy the example config file to ```oonib.conf```.
+ cp oonib.conf.example oonib.conf
+
+Then edit your configuration to fit your needs. The fields you should probably
+end up changing are ```report_dir``` (the public web server directory where you
+would like ooni-probe clients to be able to submit reports to, for example, if
+the clients should submit POSTs to https://abcdef0123456789.onion/report then
+this would simply be ```'report'```) and ```tor_datadir``` (where you would
+like the spawned Tor process to keep its data). If you compiled Tor yourself,
+you'll likely want to specify it for the ```tor_binary``` option.
+
+## Generate self signed certs for OONIB
If you want to use the HTTPS test helper, you will need to create a certificate:
openssl genrsa -des3 -out private.key 4096
@@ -34,13 +85,15 @@ If you want to use the HTTPS test helper, you will need to create a certificate:
openssl rsa -in private.key.org -out private.key
openssl x509 -req -days 365 -in server.csr -signkey private.key -out certificate.crt
rm private.key.org
+ rm server.csr
-Don't forget to update oonib/config.py options helpers.ssl.private_key and
-helpers.ssl.certificate
+If you decide to put your certificate and key somewhere else, don't forget to
+update oonib.conf options ```helpers.ssl.private_key``` and
+```helpers.ssl.certificate```!
-# Redirect low ports with iptables
-
-The following iptables commands will map connections on low ports to those bound by oonib
+## Redirect low ports with iptables
+The following iptables commands will map connections on low ports to those
+bound by oonib:
# Map port 80 to config.helpers.http_return_request.port (default: 57001)
iptables -t nat -A PREROUTING -p tcp -m tcp --dport 80 -j REDIRECT --to-ports 57001
@@ -51,35 +104,6 @@ The following iptables commands will map connections on low ports to those bound
# Map port 53 tcp to config.helpers.dns.tcp_port (default: 57005)
iptables -t nat -A PREROUTING -p tcp -m tcp --dport 53 -j REDIRECT --tor-ports
-# Install Tor (Debian).
-
-You will need a Tor binary on your system. For complete instructions, see also:
-
- https://www.torproject.org/docs/tor-doc-unix.html.en
- https://www.torproject.org/docs/rpms.html.en
-
-Add this line to your /etc/apt/sources.list, replacing <DISTRIBUTION>
-where appropriate:
-
- deb http://deb.torproject.org/torproject.org <DISTRIBUTION> main
-
-Add the Tor Project gpg key to apt:
-
- gpg --keyserver keys.gnupg.net --recv 886DDD89
- gpg --export A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89 | sudo apt-key add -
- # Update apt and install the torproject keyring, tor, and geoipdb
- apt-get update
- apt-get install deb.torproject.org-keyring tor tor-geoipdb
-
-# Configure oonib
-
-Copy the example config file
-
- cp oonib.conf.example oonib.conf
-
-Then edit your configuration to fit your needs. The fields you should probably
-end up changing are `tor_binary`, `report_dir` and `tor_datadir`.
-
# (For Experts Only) Tor2webmode:
WARNING: provides no anonymity! Use only if you know what you are doing!
@@ -122,10 +146,9 @@ Build Tor with enable-tor2web-mode
./autogen.sh ; ./configure --enable-tor2web-mode ; make
Copy the tor binary from src/or/tor somewhere and set the corresponding
-options in oonib/config.py
+options in oonib.conf.
# To launch oonib on system boot
-
To launch oonib on startup, you may want to use supervisord (www.supervisord.org)
The following supervisord config will use the virtual environment in
/home/ooni/venv_oonib and start oonib on boot:
More information about the tor-commits
mailing list