GitHub Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage
Edit page

Monitoring VPN Interference with OONI

Alternative title: how to expand our knowledge about what works and what not in different parts of the world.

In which we give you, dear reader, some pointers to get you started on th exciting world of crowd-sourced internet censorship research.

Using a VPN, or using software that behaves like a VPN, may be illegal in your country. If you suspect this to be the case, weight the risks and plan risk mitigation before proceeding. The OONI probes we talk about in this page behaves as if it was a VPN tool, and can be even more noisy in the network than a regular VPN, so it’s possible that using it gets you into trouble.
You are about to enter the OONI contributors area. Please read carefully the Things you should know before running OONI Probe and make sure you understand the implications.

Why we need moar data

Still with us? Good. They say a meme is more powerful than a thousand words, so here we go:

One Does Not Simply Collect Enough OONI Data
One Does Not Simply Collect Enough OONI Data

Things change very quickly when we’re talking about the situation of what’s blocked and what not in a context where (strong) censorship happens. The "same" experiment can throw different results depending on the time of the day, the day of the week, the month, the network you’re in (for instance, mobile netwoks regularly use different filtering rules than landlines). Because of this, we need as much data as we can get.

That said - it’s no surprise if your school, university, local bar or small network is blocking the use of a VPN. We’re interested mostly in systematic blocking in difficult contexts - where usually strong repression is also happening.

This document is about two main things:

  1. Measuring availability of Riseup servers.

  2. Measuring if the OpenVPN protocol works (for simplicity, without obfuscation, but more about that later).

A big shout out to all anonymous contributors who routinely help us check if our infrastructure is censored. You’re the MVP!

Pre-requisites and assumptions

  • This document assumes the reader has a running setup of Docker.

  • This document assumes that RiseupVPN is the target provider we’re interested in measuring. The probes can be adapted to monitor endpoints for different VPN providers (to some extent, this will be easier if those providers are also using LEAP VPN, like CalyxVPN or SurVPN). YMMV.

In the past, OONI Probe shipped a RiseupVPN experiment, that basically tried to discover a few VPN gateways for Riseup.

That experiment was disabled temporarily because it was prone to false positives. We tried improve it, and hopefully it will be enabled soon in the regular versions of the probe.

At the same time, we’re excited about the upcoming work to support testing of the OpenVPN protocol in OONI. That will allow us to test a full OpenVPN handshake in a wey that is more similar to how the "real thing" works.

In the near future, this will also allow us to do a very cool thing: we’re working on special builds of Bitmask that are able to run precise network diagnostics - and behave like if they were an OONI probe.

The two PRs we need are still in progress - so until they are landed in the OONI codebase we can demonstrate its use by cherry-picking a few commits from different branches. But be warned that, for now, all this is bleeding edge stuff. Please get in contact if you have doubts about its current state.

A Word Of Caution, or two

Did we already mentioned that this is a very good moment to read the Things you should know before running OONI Probe? Better be safe than sorry :wink:

API Connectivity check

One simple check we can do is testing whether access to the API is blocked or not. For riseup this will be black.riseup.net

We will not only connect to the API server, but also cross-check how it is resolved across multiple DNS providers.

We wil use a custom build of miniooni, the command-line version of the OONI Probe, that contains a few experimental patches that we need.

Until the PR#846 is merged, we will use a build from docker: miniooni-unofficial. You can also build the container yourself. It is a single-executable container, and it is used almost like a normal miniooni binary.

This is a convenience, unofficial build, to be able to test experimental functionality before it’s merged upstream.

Run a webconnectivity test against black.riseup.net:

docker run ainghazal/miniooni-unofficial web_connectivity -n -i https://black.riseup.net


  • docker run ainghazal/miniooni-unofficial - Run the custom miniooni container. All that follows is arguments to miniooni.

  • web_connectivity - a test to run. This one performs DNS and connection checks.

  • -n - Do not submit results to the OONI data collector.

  • -i <input> - Test input. For web_connectivity, it is an address to test connection to.

  • https://black.riseup.net - address of our API Server. We try to connect to it, and log a lot of useful info in the process.

Making it work

Did it work? No? Good. We left out a commandline flag, because we expect you to find how to accept the informed consent :grin:

Sending the report

If you feel comfortable sharing the report with OONI community (and by extension, us), re-run with -n flag omitted.

If the OONI infra itself is censored in your country, you should play with the --tunnel parameter. You can try using --tunnel tor for regular Tor (you can also specify a custom tor binary), or --tunnel torsf to try Tor+Snowflake as the method to contact the OONI backend. If all that fails, alternatively you can try to supply your own --proxy (it requires that you find a circumvention method yourself, which might be a socks proxy via an SSH tunnel, etc. Be creative!).

OpenVPN protocol check

Sometimes either OpenVPN protocol itself or a few gateways from the provider in particular can be censored.

To figure out the exact situation with your ISP, we can make miniooni try the OpenVPN protocol handshake, and also try a roster of gateways to test connecting to.


(Optional) A Closer Look

There, one can see that we perform an openvpn test (right now it will work only with the unfficial build, not with the regular miniooni) against a number of VPN gateways.

We also pass certificates to connect to RiseupVPN.

Be aware that, in case you want to craft your own oonirun descriptors, you will have to refresh these certificates from time to time.

Sending the report

See previous section


Again, thank you for participating in censorship monitoring. With your help, the censorship circumvention community can try to learn how to unblock VPN access for more people :heart:.

To leave feedback, please open an issue on our circumvention discussion repo.