EOTK to Onionspray migration tutorial¶

Onion Service Operators wanting to move from EOTK to Onionspray may need to do a few steps to start using code from the new repository.

This tutorial is a reference in how you can migrate your setup.

Tip

When migrating, do not reuse your existing EOTK installation. Instead, install Onionspray in another folder and copy over your configuration files and keys.

Info

If you run into any problem happens when migrating, you can safely switch to the old EOTK repository to gain time to troubleshoot.

Note

Report problems at the Onionspray issue queue.

Recommended migration procedure¶

1. Install Onionspray¶

Example using Debian bookworm:

sudo apt update
sudo apt install -y git
git clone https://gitlab.torproject.org/tpo/onion-services/onionspray.git
cd onionspray
./opt/build-debian-bookworm.sh

Installation procedures for other systems can be found at the installation guide.

2. Copy your configuration files¶

Assuming you're inside the Onionspray folder, run this command:

cp /path/to/eotk/*.*conf .

Then rename:

eotk-site.conf to onionspray-site.conf.
eotk-workers.conf to onionspray-workers.conf.

3. Copy your Onion Service keys¶

Now copy the Onion Service keys:

cp -r /path/to/eotk/secrets.d secrets

4. Reconfigure your projects¶

Run this command for each project (say myproject.conf) to configure it:

./onionspray config myproject.conf

5. Copy your HTTPS certificates¶

Run this command for each project (say myproject) to copy your existing HTTPS certificates:

cp /path/to/eotk/projects.d/myproject.d/ssl.d/* projects/myproject/ssl/

7. Copy old logs (optional)¶

Optionally copy old log files from each project:

cp /path/to/eotk/projects.d/myproject.d/log.d/* projects/myproject/log/

6. Start Onionspray¶

Now it's time to start Onionspray:

./onionspray bounce -a

If you prefer, you can stop EOTK before doing this (see the next step).

7. Stop EOTK¶

You can keep both EOTK and Onionspray running in parallel for a while to try a seamless migration (due to load balancing properties), or jumping straight away to stop EOTK by running this command:

/path/to/eotk/eotk stop -a

8. Replacing cronjobs and initialization scripts¶

Don't forget to update your initialization scripts and cronjobs to use the new name, folder and onionspray script.

You can use the onionspray command to generate new scripts:

./onionspray make-scripts

And then replace the EOTK boot and cron scripts with the newer ones.