ansible-relayor

Overview

This is an Ansible role specifically designed for operators of Tor relays. You can read an introduction to the relayor role here.

Email Support: relayor-support AT riseup.net

The main aim of this role is to automate many tasks for Tor relay operators, including managing keys (OfflineMasterKey). Deploying a new Tor server is as simple as adding a new host to your inventory; no additional manual configuration is needed.

This role only handles Tor instances according to the current settings and variables. If you modify the configuration after running the playbook, such as reducing the number of Tor instances by changing tor_maxPublicIPs, it won’t remove previously configured Tor instances. Each Tor instance on a server is identified by its IPv4 and ORPort combination. If you change the ORPort (using the tor_ports variable) after the initial setup, it's treated as creating new instances rather than changing existing ones, so avoid changing tor_ports after the first setup.

Keeping the Tor package updated is not part of this Ansible role’s scope. It is recommended to enable automatic updates if your operating system supports that. You can find instructions for automatic software updates in the Tor Relay Guide for both Debian/Ubuntu and FreeBSD.

This role does not support Tor bridges.

Key Features for Tor Relay Operators

• Automation: Eliminates manual setup tasks.
• Security: Offline Ed25519 master keys are created on the Ansible host, avoiding exposure to the relay.
• Easy Key Renewal: Ed25519 signing keys are valid for 30 days by default (configurable).
• Each Tor instance runs under a separate user account.
• Utilizes IPv6 IPs automatically if available.
• Generates Tor instances automatically (default: 2; configurable).
• On Debian-based systems, Tor's Sandbox feature is enabled by default.
• Choose easily between alpha and non-alpha releases (Debian/Ubuntu/FreeBSD only).
• Backup setup automatically, allowing for easy restoration.
• Simple switches between exit relay and non-exit relay modes.
• Automatically deploys a Tor exit notice HTML page on exit relays.
• Manages MyFamily automatically.
• Prometheus integration (if enabled):
  • Automatically generates Nginx reverse proxy configuration for MetricsPort.
  • Automatically creates Prometheus scrape configurations.
  • Automatically generates configurations for monitoring ORPorts and DirPorts.
  • Includes Prometheus alert rules for Tor.

Installation

This role can be installed from Galaxy: https://galaxy.ansible.com/nusenu/relayor/.

To install, run:

ansible-galaxy install nusenu.relayor

Requirements

Control Machine Requirements

• Do not use become: yes when running this role.
• Tor version >= 0.4.8.
• Install the python-netaddr package.
• Required commands: sort, uniq, wc, cut, sed, xargs.
• OpenSSL version >= 1.0.0.
• Ansible version >= 2.16.4.
• Use Bash located in /bin/bash.

Managed Node Requirements

• A non-root user with sudo permissions.
• Python installed.
• Static IPv4 address(es) (can use multiple public IPs).
• If no public IP is available, it will use a single private IP (assumes NAT).
• Systemd (for all Linux-based systems).

Prometheus Server Requirements (only if using Prometheus features)

• Install promtool on the Prometheus server and ensure it's in the PATH for the root user.

Supported Operating Systems

• Debian 12
• OpenBSD 7.4
• FreeBSD 14.1
• Ubuntu 22.04

Supported Tor Releases

• Tor version >= 0.4.8.x

Example Playbook

A minimal playbook for setting up non-exit Tor relays might look like this:

---

- hosts: relays
  vars:
    tor_ContactInfo: [email protected]
  roles:
    - nusenu.relayor

For more examples, refer to the playbook-examples folder.

Modified Defaults

This role changes default options in torrc for better security but allows you to configure them explicitly via tor_config:

• NoExec: 0 -> 1
• Sandbox: 0 -> 1 (only on Debian)

Role Variables

All variables mentioned here are optional:

• tor_ContactInfo: Mandatory string for setting relay's contact information.
• tor_signingkeylifetime_days: Duration (in days) that Ed25519 signing keys are valid for (default: 30).
• tor_config: Dictionary for torrc settings and their values.
• tor_ports: Dictionary to select ORPort and DirPort for instances.
• Other variables control aspects like directory paths, nickname, metrics settings, exit policies, etc.

Security Considerations

This role utilizes Tor's OfflineMasterKey feature, exposing only temporary signing keys. Ensure to implement adequate security measures since the control machine stores all relay keys.

Integration Testing

This Ansible role includes a .kitchen.yml file for testing against virtual machines using Vagrant. You can set it up for development or integration testing.

Before you begin, install the required gem packages:

gem install test-kitchen kitchen-ansiblepush kitchen-vagrant

Use kitchen list to view available test instances and kitchen test <instance> to execute tests on specific configurations.

Origins

This project originates from https://github.com/david415/ansible-tor, with significant changes since its inception.