Deploying Tor Relays within Minutes

Automatically deploying Tor Relays with Ansible

What is Ansible?

“Ansible is an IT automation tool. It can configure systems, deploy software, and orchestrate more advanced IT tasks […]

Ansible’s main goals are simplicity and ease-of-use.”
(quote from docs.ansible.com)

Ansible is agent-less and you can easily run ansible from your laptop to control a single or many relays. The machine running ansible to manage other machines is called the ansible control machine. You only need one control machine. The control machine must be a Linux or Unix based system (Windows is not supported). The machine that gets configured by ansible is called a managed node. The configuration and tasks to perform are pushed from the control machine to the managed nodes over SSH. Since SSH is the standard protocol to manage Linux/BSD servers you do not need any additional software on your servers except python (which often is already installed by default as well).

For a longer ansible introduction see this 19min screencast by @jweissig_
https://sysadmincasts.com/episodes/43-19-minutes-with-ansible-part-1-4

Ansible Roles

To easily reuse existing ansible configurations one can use ansible roles. A role typically installs and configures a certain piece of software like a SSH server, a webserver and so on.

relayor: An Ansible role for Tor Relay Operators

With relayor I created an ansible role to help setup and manage tor relays automatically, requiring minimal configuration and
supporting multiple GNU/Linux and BSD operating systems.

Automation makes it easy to use features that are to cumbersome to use manually (like tor’s OfflineMasterKey security feature to protect your relay’s Ed25519 master key) or to configure relays according to best practices without additional effort (MyFamily configuration).

Getting started with relayor

We assume that you do not have ansible installed and your target server is a fresh installation with regards to tor (not in use yet).

Configuring the Ansible Control Machine (i.e. your Laptop)

In this guide I’m using Debian “stretch” on the control machine, but apart from the installation of ansible and tor packages on
the control machine everything is pretty much distribution independent.

Refer to the official documentation for ansible package installation instructions if you are not using Debian stretch. Installing ansible is only required on the control machine, you do not need to install ansible on your tor relays (aka ‘managed nodes’).

When choosing your ansible control machine be aware that it stores all your relay keys, so choose the safest machine you have. Your disk (or at least your home folder) should be encrypted.

(commands starting with the “#” prompt are expected to run as root, “$” as user)

# apt install ansible tor python-netaddr

On Debian the tor package will automatically enable and start a tor daemon, we do not need a tor daemon on the control machine, so we disable it:

# systemctl disable --now tor

Make sure your tor and ansible versions meet the requirements.

You might wonder: Why do I need tor on the control machine?

relayor uses the control machine as a key storage for OfflineMasterKeys. tor is needed to generate keys only, we do not configure a tor daemon on the control machine (but you could if you want to).

Lets tell ansible where to find the list of servers and where to install ansible roles. Create the following file:

~/.ansible.cfg:

[defaults]
inventory = ~/ansible/hosts
roles_path = ~/ansible/roles

Create the folder structure according to best practices:

$ mkdir ~/ansible
$ cd ~/ansible/

Inventory File

The inventory file contains a list of the servers you want to manage with ansible. The file must be at the given location (as specified in ~/.ansible.cfg). In this example we have two servers, relay1 and relay2.

~/ansible/hosts:

[relays]
relay1.example.com
relay2.example.com

Make sure you only add servers to your inventory that are running a supported operating system/version and have python installed.

Installing relayor

That is easy:

$ ansible-galaxy install nusenu.relayor
- downloading role 'relayor', owned by nusenu
- downloading role from https://github.com/nusenu/ansible-relayor/archive/v0.2.1.tar.gz
- extracting nusenu.relayor to /home/username/ansible/roles/nusenu.relayor
- nusenu.relayor was installed successfully

This will download the latest relayor version from github via HTTPS.

You can also verify git tag signatures, so you do not have to rely on github and HTTPS. The GPG fingerprint of the signing key is listed at the end of this post.

SSH Authentication

Ansible assumes that you use SSH public key authentication to authenticate to your servers (and you should!). Ansible supports also password-based authentication (-k option) but public key authentication with an ssh-agent is recommended.

Once you finished setting up your SSH public key authentication perform a simple login test with the following command (you should not get any errors):

ansible relays -m ping

sudo

relayor expects your user to have sudo permissions on the target servers, to perform tasks (i.e. to install tor) with root privileges. If your sudo configuration requires a password use the “-K” option and ansible will prompt you for it.

Note: relayor does not support remote root to encourage SSH best practices (no remote root logins).

Running playbooks

A playbook tells ansible how your servers should be configured. relayor comes with a set of example playbooks to get you started easily, you will find them in:

~/ansible/roles/nusenu.relayor/playbook-examples

The folder contains two subfolders, one for exit relays and another for non-exit relays. You can copy and modify these examples. The simplest playbook is “1_contactInfo.yml”, copy it to ~/ansible and replace the email address and remove the comment sign (“#”). Note: The provided contact information will be published with your relay descriptor.

Now you should be ready to actually run the playbook. This will create two non-exit tor instances on each server in your inventory file. Each tor instance runs with a dedicated user.

Note: Do not run ansible-playbook commands with root privileges.

$ ansible-playbook 1_contactInfo.yml 

Depending on the amount of servers, bandwidth and latency, a playbook run takes between one and several minutes.

Important Note on Relay Key Expiry

You just setup a few tor instances. They will automatically shutdown in 30 days!

Relays get a key/cert that expires in 30 days by default. When the key expires tor terminates automatically. Keys are automatically renewed every time you run your playbook. If you do not want to run your playbook once a month you can increase the interval, see the second example playbook (2_keyexpiry_90days.yml).

It is recommended to add a reoccurring calendar entry to your calendar to avoid forgetting about the key renewal requirement.

Tor (before v0.3.2.1-alpha) does not provide a way to display key expiry dates. As a stop gap solution you might use this python script to display key expiry dates.

Usage:

$ ./show-expiredate.py ~/.tor/offlinemasterkeys/*

If you are using a tor version ≥ 0.3.2.1-alpha you can use the “ — key-expiration” option.

Backup

Now its a good time to backup your relay keys, by default they are located in ~/.tor/offlinemasterkeys on your control machine.

Further Documentation

GitHub — nusenu/ansible-relayor: An Ansible role for Tor Relay Operators

https://github.com/nusenu/ansible-relayor/wiki

relayor GPG Signing Key Fingerprint

relayor git tags are signed with the following GPG key:

pub 4096R/4D705DE9 2016–02–11 [expires: 2018–07–30]
fingerprint = A7B5 DB91 CE04 C9E0 BE66 446B 8CBE 52BD 4D70 5DE9

Reporting Bugs

Github is preferred but you can also send me an email if you do not have a github account.

https://github.com/nusenu/ansible-relayor/issues

Donation

edit: goal reached, thank you!