Skip to content
OONI Docs

OONI minioonirunv2

Author@bassosimone
Last-Updated2022-08-31
Reviewed-by@hellais
Statusapproved

The official spec for OONI Run v2 is under review as ooni/spec#249. We want to start experimenting with OONI Run v2 before such a spec has been finalized. This document, in particular, describes a “mini” OONI Run v2 where miniooni users can run arbitrary OONI Run v2 “descriptors” (see below for a definition). When ooni/spec#249 is merged, it will automatically supersede this document. The main idea of this document is just to explain the subset of OONI Run v2 implemented inside the miniooni research tool until we have a complete spec.

Overview

OONI Run v1 links do not support passing options to experiments and often times are longer than the maximum message size on, for example, WhatsApp and Telegram. To fix these issues, we’re designing OONI Run v2.

The general idea is the following:

  • there is a mobile (or desktop) OONI Run v2 deeplink;

  • the deeplink eventually resolves to a URL;

  • fetching the URL returns a JSON document telling the OONI engine what to measure, called descriptor.

This document only focuses on running arbitrary v2 descriptors for research purposes using miniooni.

OONI Run v2 descriptor

We use this definition of the descriptor (which we deemed to be forward compatible with the final descriptor format):

{
  "nettests": []
}

where "nettests" is an array of objects like this:

{
  "inputs": [],
  "options": {},
  "test_name": ""
}

where:

  • "inputs" is an optional list of input strings for the nettest like the ones you would normally pass to miniooni using -i.

  • "options" is an optional map[string]any where the key is a name of an option you can pass to a miniooni experiment using -O NAME=VALUE and value is the corresponding value. The type of the value should be the type of the original field inside of the experiment’s options, which you can see with ./miniooni <experiment> --help.

  • "test_name" is the <experiment> string you would use in ./miniooni <experiment>.

(For historical reasons, “experiment”, “test”, and “nettest” are synonymous.)

Functionality

A miniooni user could run an arbitrary OONI Run v2 descriptor stored at a given URL by invoking the oonirun subcommand and passing the URL using -i. The user could specify an abitrary number of descriptor URLs. For example:

Terminal window
./miniooni oonirun -i https://example.com/a -i https://example.com/b

The OONI engine will fetch each descriptor sequentially and execute the code it would execute if the user ran ./miniooni from the command line with the specified experiment name, the given options and inputs.

The OONI engine stores the content of each descriptor inside a cache on disk inside the $OONI_HOME of miniooni (generally $HOME/.miniooni/). Conceptually, this cache is a map from the descriptor URL to the latest known content of the descriptor. (The actual implementation may differ.)

On the first run, or when the descriptor has changed, miniooni refuses to run, shows what changed, and asks the user for confirmation. There’s also a mechanism to bypass asking for confirmation that explicitly requires a user to add -y or --yes to the command line to automatically answer “yes” to all questions. (This is useful when, for example, you’re running your own descriptors.)