commit 4648dd50aa44066eec9de1526f08a2e517ea14fb Author: Arturo Filastò <art@fuffa.org> Date: Thu Dec 6 15:13:54 2012 +0100 Update report documentation with better markup and better descriptions --- docs/source/reports.rst | 34 ++++++++++++++++++++++++---------- 1 files changed, 24 insertions(+), 10 deletions(-) diff --git a/docs/source/reports.rst b/docs/source/reports.rst index cf5e008..7a49dcb 100644 --- a/docs/source/reports.rst +++ b/docs/source/reports.rst @@ -2,32 +2,46 @@ Reports ======= The reports collected by ooniprobe are stored on -https://ooni.torproject.org/reports/`reportFormatVersion`/`CC`/ +https://ooni.torproject.org/reports/ ``reportFormatVersion`` / ``CC`` / -Where `CC` is the two letter country code as specified by -http://en.wikipedia.org/wiki/ISO_3166-2. +Where ``CC`` is the two letter country code as specified by `ISO 31666-2 +<http://en.wikipedia.org/wiki/ISO_3166-2>`_. -For example the reports for Italy (`CC` is `it`) of the `reportVersion` 0.1 may +For example the reports for Italy (``CC`` is ``it``) of the ``reportVersion`` 0.1 may be found in: -:: - https://ooni.torproject.org/reports/0.1/IT/ +https://ooni.torproject.org/reports/0.1/IT/ This directory shall contain the various reports for the test using the following convention: -`ISO8601`-AS`probeASNumber`.yamloo +``dateInISO8601Format`` _ ``probeASNumber`` .yamloo + +The date is expressed using `ISO 8601 <http://en.wikipedia.org/wiki/ISO_8601`_ +including seconds and with no ``:`` to delimit hours, minutes, days. + +Like so + + ``YEAR`` - ``MONTH`` - ``DAY`` T ``HOURS`` ``MINUTES`` ``SECONDS`` Z + +The time is **always** expressed in UTC. If a collision is detected then an int (starting with 1) will get appended to the test. -For example a report that was created on the first of January 2012 at Noon (UTC -time) sharp from MIT (AS3) will be stored here: +For example if two report that are created on the first of January 2012 at Noon +(UTC time) sharp from MIT (AS3) will be stored here: :: - https://ooni.torproject.org/reports/0.1/US/2012-01-01T120000Z-AS3.yamloo + https://ooni.torproject.org/reports/0.1/US/2012-01-01T120000Z_AS3.yamloo + https://ooni.torproject.org/reports/0.1/US/2012-01-01T120000Z_AS3.1.yamloo + + +Note: it is highly unlikely that reports get created with the same exact +timestamp from the same exact ASN. If this does happen it could be index of +some malicious report poisoning attack in progress. Report format version changelog