commit fa476d07dccbfd58a186700401d2f337e8213e4b Author: Arturo Filastò art@fuffa.org Date: Sun Nov 11 18:50:09 2012 +0100
Update documentation on how to setup ooniprobe --- INSTALL | 1 - README.md | 44 ++++++++++++++++- docs/source/index.rst | 51 ++------------------ docs/source/install.rst | 119 ----------------------------------------------- 4 files changed, 45 insertions(+), 170 deletions(-)
diff --git a/INSTALL b/INSTALL deleted file mode 120000 index 5c72744..0000000 --- a/INSTALL +++ /dev/null @@ -1 +0,0 @@ -docs/source/install.rst \ No newline at end of file diff --git a/README.md b/README.md index 137386a..bb17cc7 100644 --- a/README.md +++ b/README.md @@ -29,9 +29,13 @@ On debian based systems these can be installed with:
The python dependencies required for running ooniprobe are:
- * Twisted - * Scapy >= 2.2.0 - * txtorcon + * Twisted (>12.0.0): http://twistedmatrix.com/trac/ + * PyYAML: http://pyyaml.org/ + * Scapy: http://www.secdev.org/projects/scapy/ + * pypcap: http://code.google.com/p/pypcap/ + * libdnet: http://code.google.com/p/libdnet/ + * BeautifulSoup: http://www.crummy.com/software/BeautifulSoup/ + * txtorcon: https://github.com/meejah/txtorcon
They can be installed from the requirements.txt with:
@@ -53,6 +57,40 @@ Then install OONI with:
pip install -r requirements.txt
+## Installing scapy + +Unfortunately the version of scapy that is stored on pypi is out of date, this +means that you will have to manually download and install scapy. + +This can be done like so: + + wget http://www.secdev.org/projects/scapy/files/scapy-latest.tar.gz + tar xzf scapy-latest.tar.gz + cd scapy-latest.tar.gz + cd scapy-latest + python setup.py install + +If you are not inside of a virtual env the last command will have to be: + + sudo python setup.py install + +## 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: diff --git a/docs/source/index.rst b/docs/source/index.rst index 132381f..ccfaad4 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,56 +1,13 @@ .. OONI documentation master file.
-Welcome to the OONI documentation! -================================== +Welcome to the OONI developer documentation +===========================================
- The Net interprets censorship as damage and routes around it. - John Gilmore; TIME magazine (6 December 1993) +If you are looking for how to start running the ooniprobe tool see:
-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. + https://github.com/hellais/ooni-probe#getting-started
-Getting started -*************** - -Requirements: - - * Git: http://git-scm.com/book/en/Getting-Started-Installing-Git - * Python >= 2.6: http://www.python.org/download/releases/ - * pip: http://www.pip-installer.org/en/latest/ - -On debian based systems these can be installed with: - - apt-get install git-core python python-pip python-dev - -The python dependencies required for running ooniprobe are: - - * Twisted - * Scapy >= 2.2.0 - * txtorcon - -They can be installed from the requirements.txt with: - - pip install -r requirements.txt - -You are highly recommended to do so 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. - - apt-get install python-virtualenv - -To create a new virtual environment do - - virtualenv env - -Then install OONI with: - - pip install -r requirements.txt - Contents ********
diff --git a/docs/source/install.rst b/docs/source/install.rst deleted file mode 100644 index 4a24d3a..0000000 --- a/docs/source/install.rst +++ /dev/null @@ -1,119 +0,0 @@ - -Installing OONI -=============== - -Dependencies -************ - -OONI depends on the following pieces of software. - -* Twisted (>12.0.0): http://twistedmatrix.com/trac/ -* PyYAML: http://pyyaml.org/ -* Scapy: http://www.secdev.org/projects/scapy/ - * pypcap: http://code.google.com/p/pypcap/ - * libdnet: http://code.google.com/p/libdnet/ -* BeautifulSoup: http://www.crummy.com/software/BeautifulSoup/ -* Txtorcon: https://github.com/meejah/txtorcon - -*Optional* - -* Dnspython [1]: http://www.dnspython.org/ -* Paramiko [2]: http://www.lag.net/paramiko/ - -If you would like to use Scapy to plot graphs of network activity, -or be capable of dumping obtained information to a PostScript or PDF -file, then you'll need: - - * gnuplot-py - * numpy - * Pyx - -[1][2] These dependencies will soon be removed completely. - -Debian packages ---------------- - -On debian you can install most of the dependecies with apt-get with this command:: - - apt-get install python-yaml python-scapy python-beautifulsoup python-pypcap python-dumbnet python-dnspython - -Note that debian (squeeze) distributes version 10.1.0 of python-twisted, -and ubuntu (precise) distributes version 11.1.0. -You need the following packages for twisted to compile:: - - apt-get install python-dev build-essential - -Txtorcon has the following addtitional dependencies:: - - apt-get install python-geoip python-ipaddr python-psutil - -Python virtual environmentsa (virtualenv) ------------------------------------------ - -You may prefer to install these dependencies within a python virtualenv[3]:: - - sudo apt-get install python-virtualenv virtualenvwrapper - -From the docs (/usr/share/doc/virtualenvwrapper/README.Debian): - - Virtualenvwrapper is enabled if you install the package bash-completion and - enable bash completion support in /etc/bash.bashrc or your ~/.bashrc. - - If you only want to use virtualenvwrapper you may just add - source /etc/bash_completion.d/virtualenvwrapper to your ~/.bashrc. - -Source the script or login again and set up a virtualenv:: - - mkdir $HOME/.virtualenvs - mkvirtualenv ooni-probe - -You will automatically enter the environment. easy_install and pip will install -packages inside this environment, and will not require root privileges. -[3] http://www.virtualenv.org - -Manual installation of python dependencies -------------------------------------------- - -This involves installing the dependencies installable via easy_install/pip and -the ones that are not by building them from source. - -"simple" dependencies via easy_install:: - - sudo easy_install pyyaml twisted beautifulsoup pygeoip six ipaddr psutil txtorcon - -"simple" dependencies via pip:: - - sudo pip install pyyaml twisted beautifulsoup pygeoip six ipaddr psutil txtorcon - -Manual installation of scapy ----------------------------- - -It is optimal to install scapy, libdnet and pypcap from source. This can be -done with the following code snippets. - -libdnet:: - - wget http://libdnet.googlecode.com/files/libdnet-1.12.tgz - tar xzf libdnet-1.12.tgz - cd libdnet-1.12 - ./configure && make - cd python/ - sudo python setup.py install - cd ../../ && rm -rf libdnet-1.12* - -pypcap:: - - svn checkout http://pypcap.googlecode.com/svn/trunk/ pypcap-read-only - cd pypcap-read-only/ - sudo pip install pyrex - make - sudo python setup.py install - cd ../ && rm -rf pypcap-read-only - -scapy:: - - wget http://www.secdev.org/projects/scapy/files/scapy-latest.zip - unzip scapy-latest.zip - cd scapy-2.2.0/ - sudo python setup.py install - cd ../ && rm -rf scapy-*