Skip to content

Install and configure Tor Onion Services

Notifications You must be signed in to change notification settings

systemli/ansible-role-onion

Repository files navigation

ansiblt-role-onion

Build Status Ansible Galaxy

Install and configure one or multiple Tor Onion Services (formerly known as Hidden Services).

Hostname and private key will be generated if not supplied as variable.

Hint: It may take up to one minute, until the service is announced in the tor network and reachable.

Be careful: Using the default 127.0.0.1 as Onion Service IP-address could possibly leak meta data: https://help.riseup.net/en/security/network-security/tor/onionservices-best-practices#be-careful-of-localhost-bypasses

Only supports Onion Services in version 3 previously known as Next Gen Onion Services only if tor version >= 0.3.2.1!

Role Variables

# defaults file for onion
onion_active: True
onion_ipaddr: 127.0.0.1
onion_tor_apt_state: present
onion_services:
  ssh:
    onion_hostname:
    onion_ports:
      - [22, 22]
    onion_authorized_clients: []
    onion_private_key:

onions_configuration:
  SocksPort: 9050
  SocksPolicy: "reject *"

# List of auth cookies for connecting to Authenticated Tor Onion Services.
#
onion_hid_serv_auth: []

onion_monit_enabled: False

Download

Download latest release with ansible-galaxy

ansible-galaxy install systemli.onion

Example Playbook

    - hosts: servers
      roles:
         - { role: systemli.onion }

Extended Variables Example

onion_active: True
onion_ipaddr: 192.168.3.12

onion_services:
  #
  # nextgeneration onion (v3) only available in tor >= 0.3.2.1
  # https://trac.torproject.org/projects/tor/wiki/doc/NextGenOnions#Howtosetupyourownprop224service
  #
  nextgenonion:
     onion_hostname: onionv3url.onion
     onion_ports:
        - [25, 25]
        - [587,587]
     onion_public_key_b64encoded: "\nPT0gZWQyNTUxOaYxLXB1YmxpYzogdHlwZTAgPT0AAABADSX6gVbfuClP6aBXz8V00oMw5Sovn0ZU\nftKei9UWmw==\n"
     onion_secret_key_b64encoded: "\nPT0gZWQyNTUxOaYxLXNlY3JldDogdHlwZTAgPT0AAAAYzbVMulElZeorlRoSKWG4VVVwWQN0lHac\nhpR5jLcqb2iuHQu7K9yrdRUrSUWW42gFUvl7lCDQPV7aGWQcf9TI\n"

  absentonion:
     onion_state: absent
     onion_hostname: onionv3url.onion
     onion_ports:
        - [25, 25]
        - [587,587]
     onion_public_key_b64encoded: "\nPT0gZWQyNTUxOaYxLXB1YmxpYzogdHlwZTAgPT0AAABADSX6gVbfuClP6aBXz8V00oMw5Sovn0ZU\nftKei9UWmw==\n"
     onion_secret_key_b64encoded: "\nPT0gZWQyNTUxOaYxLXNlY3JldDogdHlwZTAgPT0AAAAYzbVMulElZeorlRoSKWG4VVVwWQN0lHac\nhpR5jLcqb2iuHQu7K9yrdRUrSUWW42gFUvl7lCDQPV7aGWQcf9TI\n"

#
# Example for torrc with special onion configurations
# such as Sandboxing, custom data directory, auth cookies ...

onion_services:
  ssh:
    onion_ports:
      - [22, 22]
    onion_authorized_clients:
      - admin

onions_configuration:
  SocksPort: 9050
  SocksPolicy: "reject *"
  RunAsDaemon: 1
  # Enabling Sandbox for the first time may prevent
  # the tor service from restarting. Make sure your
  # SSH connection is not over Tor when enabling it.
  Sandbox: 1
  FetchDirInfoEarly: 1
  FetchDirInfoExtraEarly: 1
  DataDirectory: /var/lib/tor

# Hosts that specified `onion_authorized_clients` will generate
# auth cookies for restricted access. Collect those values from the
# hostname file and add them to the torrc for intended clients, e.g.
# the Ansible controller, via the list var below.
onion_hid_serv_auth:
  - "r7w3xdf3r5smxokv.onion p0xMVci7ffeQFA4IWkcBxR # client: admin"

Tests

For developing and testing this role we use Github Actions, ansible-lint, Molecule, and Vagrant.

Run local tests with:

molecule test

License

GPLv3

Author Information

https://www.systemli.org