[tor-commits] [ooni-probe/master] Update readme with some more useful information

Tue Jul 24 11:36:46 UTC 2012

commit bf2079f09b8257be0acd4bb2d76a0f362b6943bd
Author: Arturo FilastÃ² <arturo at filasto.net>
Date:   Tue Jul 24 13:34:52 2012 +0200

    Update readme with some more useful information
    convert readme to markdown.
---
 README    |   70 ----------------------------------------------
 README.md |   93 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 93 insertions(+), 70 deletions(-)

diff --git a/README b/README
deleted file mode 100644
index 75262bf..0000000
--- a/README
+++ /dev/null
@@ -1,70 +0,0 @@
-ooni-probe - 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.
-
-With the belief that unfettered access to information is a intrinsic human right,
-OONI seeks to observe levels of surveillance, censorship, and network discrimination
-in order for people worldwide to have a clearer understanding of the ways in
-which their access to information is filtered.
-
-The end goal of OONI is to collect data which can show an accurate
-topology of network interference and censorship. Through this topology, it will be
-possible to see what the internet looks like from nearly any location, including
-what sites are censored, or have been tampered with, and by whom. We're calling
-it filternet.
-
-OONI uses open methodologies and the data will be provided in raw
-format to allow any researcher to indipendently draw their conclusions
-from the results OONI tests.
-
-There are currently projects aimed at measuring censorship in one
-way or another but they either use non open methodologies or their
-tools are not open sources. OONI aims at filling up this gap by
-creating the first open source framework for developing network
-tests and collecting data on censorship.
-
-OONI revolves around three major concepts: Assets, Tests and
-Reports.
-
-# Assets
-
-Assets are the inputs used inside Tests to detect censorship events.
-These can be URL lists, keywords, ip addresses, packets or any kind
-of set of data.
-In the python specific implementation this is represented as a python
-iterable object. This means that the Testing framework will be able
-to iterate through every element in the Asset.
-
-# Tests
-
-This is the core of OONI. These are the actual tests that will be run
-using as input (if an input is required) the Assets.
-Tests can be summarized as an experiment and a control. The control
-represents the expected result and the experiment is the network operation
-being performed on the live network. If the experiment does not match up
-with the control then a censorship event had occured.
-
-OONI probe provides some useful functionality to the application developer
-that may be useful when developing censorship detection tests. For example
-it is possible to make a request over the Tor network easily or use a fast
-and flexible non-blocking HTTP client implementation.
-
-# Reports
-
-This is the data that is collected from the test. OONI probe provides a
-flexible means of storing results and uploading this data to a remote
-server or a flat file.
-
-The Test developer should include in the report as much data as possible
-and can contain raw packet dumps as well as structured synthetic results.
-
-In future on top of ooni-probe Reports it will be possible to develop
-flexible post-processing tools to allow data-visualization guru's to
-properly visualize and contextualize the resulting data.
-
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b39cb2b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,93 @@
+# ooni-probe - 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.
+
+You must therefore run from the root of the repo:
+
+    export PYTHONPATH=$PYTHONPATH:`pwd`
+
+Then to see what tests are available:
+
+    cd ooni
+    python ooniprobe.py
+
+If you see some errors see INSTALL to install the missing dependencies.
+
+To list the help for a specific test:
+
+    python ooniprobe.py httpt --help
+
+
+# More details
+
+With the belief that unfettered access to information is a intrinsic human right,
+OONI seeks to observe levels of surveillance, censorship, and network discrimination
+in order for people worldwide to have a clearer understanding of the ways in
+which their access to information is filtered.
+
+The end goal of OONI is to collect data which can show an accurate
+topology of network interference and censorship. Through this topology, it will be
+possible to see what the internet looks like from nearly any location, including
+what sites are censored, or have been tampered with, and by whom. We're calling
+it filternet.
+
+OONI uses open methodologies and the data will be provided in raw
+format to allow any researcher to indipendently draw their conclusions
+from the results OONI tests.
+
+There are currently projects aimed at measuring censorship in one
+way or another but they either use non open methodologies or their
+tools are not open sources. OONI aims at filling up this gap by
+creating the first open source framework for developing network
+tests and collecting data on censorship.
+
+OONI revolves around three major concepts: Assets, Tests and
+Reports.
+
+## Assets
+
+Assets are the inputs used inside Tests to detect censorship events.
+These can be URL lists, keywords, ip addresses, packets or any kind
+of set of data.
+In the python specific implementation this is represented as a python
+iterable object. This means that the Testing framework will be able
+to iterate through every element in the Asset.
+
+## Tests
+
+This is the core of OONI. These are the actual tests that will be run
+using as input (if an input is required) the Assets.
+Tests can be summarized as an experiment and a control. The control
+represents the expected result and the experiment is the network operation
+being performed on the live network. If the experiment does not match up
+with the control then a censorship event had occured.
+
+OONI probe provides some useful functionality to the application developer
+that may be useful when developing censorship detection tests. For example
+it is possible to make a request over the Tor network easily or use a fast
+and flexible non-blocking HTTP client implementation.
+
+## Reports
+
+This is the data that is collected from the test. OONI probe provides a
+flexible means of storing results and uploading this data to a remote
+server or a flat file.
+
+The Test developer should include in the report as much data as possible
+and can contain raw packet dumps as well as structured synthetic results.
+
+In future on top of ooni-probe Reports it will be possible to develop
+flexible post-processing tools to allow data-visualization guru's to
+properly visualize and contextualize the resulting data.
+

