This guide documented how to use ansible to setup tor relays on a VPS.


  • A local PC, installed with Ubuntu 20.04 LTS
    • can connect to VPS with SSH key
  • A VPS, installed with Ubuntu 20.04 LTS
    • port 443 should be opened in firewall
    • user account should have sudo permission


  1. Install python3 and tor on local PC

    $ sudo apt update
    $ sudo apt install python3 tor
  2. Install ansible on local PC

    $ pip3 install ansible
  3. Install nusenu.relayor

    $ ansible-galaxy install nusenu.relayor
  4. Install nusenu.relayor dependency on local PC

    $ pip3 install netaddr
  5. Create new workspace

    $ mkdir ~/my-tor-relays
    $ cd ~/my-tor-relays
  6. Create hosts file

    $ touch ./hosts

    hosts contains connection to the VPS. It should looks like


    [tag] is for grouping relays with the same configuration.

    For example, we may have three VPS, two with 1TB monthly traffic and one with 2TB month traffic. Then we can have two tags [1000GB] and [2000GB], and set the monthly traffic allowance on the relays in these two groups to 1TB and 2TB respectively. Our hosts may looks like

  7. Create playbook file

    $ touch ./playbook.yml

    playbook.yml contains configuration for the relay. The file should at least contains our contact information with tor_ContactInfo. It should look like:

    - hosts: tag
       - nusenu.relayor

    If we want to have two groups of relays with different monthly traffic allowed, we can set the monthly limit with tor_AccountingMax, such that our playbook.yml may looks like

    - hosts: 1000GB
       tor_AccountingMax: 1000 GBytes
       - nusenu.relayor
    - hosts: 2000GB
       tor_AccountingMax: 2000 GBytes
       - nusenu.relayor
  8. Execute the playbook to enable tor relay service on VPS

    $ ansible-playbook playbook.yml -l all -i ./hosts

    After successfully executing the playbook, we should follow Relay Post-install and good practices to ensure our service is up and running.


In this post, we walked throught how to setup tor relay service on VPS using nusenu.relayor.

Two options tor_ContactInfo and tor_AccountingMax are introduced. There are many more available options, please refer to ansible-relayor doc to see more.

It is encouraged to use ContactInfo Information Sharing Specification to publish useful contact information with tor_ContactInfo.

It is recommanded to read this blog post to understand the lifecycle of a new relay that we just setup.