[tor-commits] [ooni-probe/master] Add support for generating manpages from rst files.
art at torproject.org
art at torproject.org
Fri Oct 14 19:00:56 UTC 2016
commit 41f80dbc1cbc706ff4d08e35cc82d1e05fa95f21
Author: Arturo Filastò <arturo at filasto.net>
Date: Fri Oct 14 19:35:32 2016 +0200
Add support for generating manpages from rst files.
Add manpages for ooni*
---
docs/source/conf.py | 7 +-
docs/source/manual/oonideckgen.rst | 17 ++++
docs/source/manual/ooniprobe-agent.rst | 103 ++++++++++++++++++++++++
docs/source/manual/ooniprobe.rst | 140 +++++++++++++++++++++++++++++++++
docs/source/manual/oonireport.rst | 85 ++++++++++++++++++++
docs/source/manual/ooniresources.rst | 15 ++++
6 files changed, 365 insertions(+), 2 deletions(-)
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 8600641..e3c6544 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -218,8 +218,11 @@ latex_documents = [
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
- ('index', 'ooniprobe', u'an internet censorship measurement tool',
- [u'The Tor Project'], 1)
+ ('manual/oonideckgen', 'oonideckgen', u'DEPRECATED ooni tool', [u'The Tor Project'], 1),
+ ('manual/ooniprobe-agent', 'ooniprobe-agent', u'an internet censorship measurement tool, system daemon.', [u'The Tor Project'], 1),
+ ('manual/ooniprobe', 'ooniprobe', u'an internet censorship measurement tool', [u'The Tor Project'], 1),
+ ('manual/oonireport', 'oonireport', u'upload ooniprobe measurements', [u'The Tor Project'], 1),
+ ('manual/ooniresources', 'ooniresources', u'DEPRECATED ooni tool', [u'The Tor Project'], 1),
]
# If true, show URL addresses after external links.
diff --git a/docs/source/manual/oonideckgen.rst b/docs/source/manual/oonideckgen.rst
new file mode 100644
index 0000000..cbdddc4
--- /dev/null
+++ b/docs/source/manual/oonideckgen.rst
@@ -0,0 +1,17 @@
+oonideckgen - DEPRECATED
+========================
+
+Synopsis
+--------
+
+**oonideckgen**
+
+Description
+-----------
+
+:program:`oonideckgen`, has now been superseded by the new test
+deck format.
+You will will find all the decks you need to run inside of
+/usr/share/ooni/decks-available/ and these can be run with:
+
+ :program:`ooniprobe -i /usr/share/ooni/decks-available/web.yaml`
diff --git a/docs/source/manual/ooniprobe-agent.rst b/docs/source/manual/ooniprobe-agent.rst
new file mode 100644
index 0000000..1958ab5
--- /dev/null
+++ b/docs/source/manual/ooniprobe-agent.rst
@@ -0,0 +1,103 @@
+ooniprobe-agent
+===============
+
+Synopsis
+--------
+
+**ooniprobe-agent** start | stop | run | status
+
+Description
+-----------
+
+:program:`ooniprobe-agent`, is a system daemon responsible for automatically
+running OONI measurements and exposing a web user interface. The web user
+interface is accessible by default on http://127.0.0.1:8842/
+
+Options
+-------
+
+--help
+ Display help and exit.
+
+--version
+ Display the ooniprobe version and exit.
+
+Commands
+--------
+
+**start**
+Start the ooniprobe-agent in the background
+
+**stop**
+Stop the ooniprobe-agent
+
+**status**
+Show status of the ooniprobe-agent
+
+**run**
+Run the ooniprobe-agent in the foreground
+
+
+ooniprobe
+---------
+
+Read this before running ooniprobe!
+...................................
+Running ooniprobe is a potentially risky activity. This greatly depends on the
+jurisdiction in which you are in and which test you are running. It is
+technically possible for a person observing your internet connection to be
+aware of the fact that you are running ooniprobe. This means that if running
+network measurement tests is something considered to be illegal in your country
+then you could be spotted.
+
+Furthermore, ooniprobe takes no precautions to protect the install target machine
+from forensics analysis. If the fact that you have installed or used ooni
+probe is a liability for you, please be aware of this risk.
+
+What is this?
+.............
+
+ooniprobe is the command line tool that volunteers and researches interested in
+contributing data to the project should be running.
+
+If you are interested in using ooniprobe from a graphical user interface
+refer to :program:`ooniprobe-agent` and see how to run that.
+
+ooniprobe allows the user to select what test should be run and what backend
+should be used for storing the test report and/or assisting them in the running
+of the test.
+
+ooniprobe tests are divided into two categories: **Traffic Manipulation** and
+**Content Blocking**.
+
+**Traffic Manipulation** tests aim to detect the presence of some sort of
+tampering with the internet traffic between the probe and a remote test helper
+backend. As such they usually require the selection of a oonib backend
+component for running the test.
+
+**Content Blocking** are aimed at enumerating the kind of content that is
+blocked from the probes network point of view. As such they usually require to
+have specified an input list for running the test.
+
+Examples
+--------
+
+Run the web_connectivity test on http://torproject.org:
+
+ :program:`ooniprobe web_connectivity --url http://torproject.org/`
+
+Run the http_invalid_request_line test to detect middleboxes:
+
+ :program:`ooniprobe http_invalid_request_line`
+
+Run the http_header_field_manipulation test to detect middleboxes:
+
+ :program:`ooniprobe http_header_field_manipulation`
+
+List all the available tests:
+
+ :program:`ooniprobe -s`
+
+Start the web user interface:
+
+ :program:`ooniprobe -w`
diff --git a/docs/source/manual/ooniprobe.rst b/docs/source/manual/ooniprobe.rst
new file mode 100644
index 0000000..7d71795
--- /dev/null
+++ b/docs/source/manual/ooniprobe.rst
@@ -0,0 +1,140 @@
+ooniprobe
+=========
+
+Synopsis
+--------
+
+**ooniprobe** [*options*] ([*test name*] | [*path to nettest*.py])
+
+Description
+-----------
+
+:program:`ooniprobe`, is a tool for performing internet censorship
+measurements. Our goal is to achieve a common data format and set of
+methodologies for conducting censorship related research.
+
+Options
+-------
+
+-h, --help
+ Display help and exit.
+
+-n, --no-collector
+ Disable writing to collector
+
+-N, --no-njson
+ Disable writing to disk
+
+-g, --no-geoip
+ Disable geoip lookup on start
+
+-s, --list
+ List the currently installed ooniprobe nettests
+
+-v, --verbose
+ Show more verbose information
+
+-w, --web-ui
+ Start the web UI
+
+-z, --initialize
+ Initialize ooniprobe to begin running it
+
+-o, --reportfile PATH_TO_FILE
+ Specify the report file name to write to.
+
+-i, --testdeck PATH_TO_DECK
+ Specify as input a test deck: a yaml file containing the tests to run and their arguments.
+
+-c, --collector COLLECTOR_ADDRESS
+ Specify the address of the collector for test results. In most cases a user
+ will prefer to specify a bouncer over this.
+
+-b, --bouncer BOUNCER_ADDRESS
+ Specify the bouncer used to obtain the address of the collector and test helpers.
+
+-l, --logfile PATH_TO_LOGFILE
+ Write to this logs to this filename.
+
+-O, --pcapfile PATH_TO_PCAPFILE
+ Write a PCAP of the ooniprobe session to this filename.
+
+-f, --configfile PATH_TO_CONFIG
+ Specify a path to the ooniprobe configuration file.
+
+-d, --datadir
+ Specify a path to the ooniprobe data directory.
+
+-a, --annotations key:value[,key2:value2]
+ Annotate the report with a key:value[, key:value] format.
+
+-P, --preferred-backend onion|https|cloudfront
+ Set the preferred backend to use when submitting results and/or
+ communicating with test helpers. Can be either onion, https or cloudfront
+
+--version
+ Display the ooniprobe version and exit.
+
+ooniprobe
+---------
+
+Read this before running ooniprobe!
+...................................
+Running ooniprobe is a potentially risky activity. This greatly depends on the
+jurisdiction in which you are in and which test you are running. It is
+technically possible for a person observing your internet connection to be
+aware of the fact that you are running ooniprobe. This means that if running
+network measurement tests is something considered to be illegal in your country
+then you could be spotted.
+
+Furthermore, ooniprobe takes no precautions to protect the install target machine
+from forensics analysis. If the fact that you have installed or used ooni
+probe is a liability for you, please be aware of this risk.
+
+What is this?
+.............
+
+ooniprobe is the command line tool that volunteers and researches interested in
+contributing data to the project should be running.
+
+If you are interested in using ooniprobe from a graphical user interface
+refer to :program:`ooniprobe-agent` and see how to run that.
+
+ooniprobe allows the user to select what test should be run and what backend
+should be used for storing the test report and/or assisting them in the running
+of the test.
+
+ooniprobe tests are divided into two categories: **Traffic Manipulation** and
+**Content Blocking**.
+
+**Traffic Manipulation** tests aim to detect the presence of some sort of
+tampering with the internet traffic between the probe and a remote test helper
+backend. As such they usually require the selection of a oonib backend
+component for running the test.
+
+**Content Blocking** are aimed at enumerating the kind of content that is
+blocked from the probes network point of view. As such they usually require to
+have specified an input list for running the test.
+
+Examples
+--------
+
+Run the web_connectivity test on http://torproject.org:
+
+ :program:`ooniprobe web_connectivity --url http://torproject.org/`
+
+Run the http_invalid_request_line test to detect middleboxes:
+
+ :program:`ooniprobe http_invalid_request_line`
+
+Run the http_header_field_manipulation test to detect middleboxes:
+
+ :program:`ooniprobe http_header_field_manipulation`
+
+List all the available tests:
+
+ :program:`ooniprobe -s`
+
+Start the web user interface:
+
+ :program:`ooniprobe -w`
diff --git a/docs/source/manual/oonireport.rst b/docs/source/manual/oonireport.rst
new file mode 100644
index 0000000..a7dced0
--- /dev/null
+++ b/docs/source/manual/oonireport.rst
@@ -0,0 +1,85 @@
+oonireport
+==========
+
+Synopsis
+--------
+
+**oonireport** [*options*] upload | status [*path to report*]
+
+Description
+-----------
+
+:program:`oonireport` is a tool for viewing which ooniprobe
+reports have not been submitted to a collector and upload them.
+
+
+:program:`ooniprobe -i /usr/share/ooni/decks-available/web.yaml`
+
+Options
+-------
+
+-d, --default-collector
+ Upload the reports to the default collector that is looked up
+ with the canonical bouncer.
+
+-f, --configfile
+ Specify the configuration file to use.
+
+-c, --collector
+ Specify the collector to upload the result to.
+
+-b, --bouncer
+ Specify the bouncer to query for a collector.
+
+ --version
+
+ --help Display this help and exit.
+
+Commands
+--------
+
+**upload**
+
+If no argument is specified all the reports that have not been
+submitted will be submitted to either the collector specified as
+an option (-c) or to the collector that was previously used.
+
+If a report file is specified then only that report file will be
+uploaded
+
+**status**
+
+Outputs all of the reports that are either "not uploaded",
+"incomplete" or "pending".
+
+The possible statuses are:
+
+not-created
+
+If it has not been created, because the user specified to not use a
+collector.
+
+creation-failed
+
+If we attempted to create the report, but failed to do so either because
+the collector does not accept our report or because it was unreachable at the
+time.
+
+created
+
+If the report has been successfully created, but has not yet been
+closed.
+
+incomplete
+
+If the report has been created, but we have failed to update the
+report with some data.
+
+oonireport
+----------
+
+This tool is used to upload reports that are stored on the users
+filesystem and have not been submitted to a collector. This can be
+either because the collector was unreachable when we attempted to
+submit the report or because the policy of the collector did not
+support the specified test.
diff --git a/docs/source/manual/ooniresources.rst b/docs/source/manual/ooniresources.rst
new file mode 100644
index 0000000..b7840e8
--- /dev/null
+++ b/docs/source/manual/ooniresources.rst
@@ -0,0 +1,15 @@
+ooniresources - DEPRECATED
+========================
+
+Synopsis
+--------
+
+**ooniresources**
+
+Description
+-----------
+
+:program:`ooniresources`, has now been superseded by a system that
+automatically manages downloads of new resources.
+
+There is no reason to use this anymore.
More information about the tor-commits
mailing list