Prototype¶

The current Oniongroove codebase is a prototype.

It's available for testing and tinkering.

Characteristics¶

Based on Arti and OpenResty.
The full specification is not implemented yet.
Lacks many configuration options both on the Onion Service and HTTPS sides.
Only onionsites based on the HTTPS rewriting proxy are supported right now.
Light configuration format: only a mapping between Onion Service addresses and it's DNS-based upstream domain names is needed in the proxy layer.
On the fly self-signed certificate generation: HTTPS certificates are generated in the first TLS handshake if they're not already present in the file system. This allows testing how an onionsite would look like if there was already some automated way to get CA-validated certificates.

This prototype currently requires Docker and Docker Compose properly installed. The provision script serves as an example in how to do that.

Get Oniongroove with it's submodules directly from the repository using

git clone --recursive https://gitlab.torproject.org/tpo/onion-services/oniongroove.git

Once installed, you enter the oniongroove folder an run commands from there.

The prototype relies in the following configuration folder structure:

configs:
- arti: holds compiled Arti configuration; do not edit those files directly.
- openresty: holds compiled OpenResty configuration; do not edit those files directly.
- oniongroove.yaml: default and sample Oniongroove configuration; leave this file as a reference.
- Other custom YAML configurations.

Begin by copying the sample configuration:

cp configs/oniongroove.yaml configs/myprovider.yaml

Edit this file to suit your needs.

The main tool is the oniongroove script:

./oniongroove --help

To start Oniongroove, use the start action and pass a configuration file path:

./oniongroove start configs/myprovider.yaml