commit 41f80dbc1cbc706ff4d08e35cc82d1e05fa95f21 Author: Arturo Filastò arturo@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/%60 + +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/%60 + +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.