Last Updated 4/21/2018

Previously I had been maintaining a long bash script to provision an "onion router," a personal router that can isolate a small network to only using the Tor Anonyminity Network. That script is rather ugly and hacked together, it will still be maintained, but for now I prefer to provision with Ansible. Down the road there will also be the necessary code to provision "private bridges" more info here that can use obsfuscation for those users from places that block the usage of Tor like China, Iran, and a few other places where governments block Tor or jail Tor users.

The code is over on bitbucket at:

Now a quck tutorial on how to use Ansible to deploy an onion-router.


In this example I am using the following versions of software:

Minor privisioning of the Raspberry Pi needs to be done in order to SSH into it. After writing the Raspbian image to your SD Card boot it up and you will need to login with the default username and password with a keyboard connected to the Pi.

Username: pi
Password: raspberry

Next you need to start the SSH daemon. Ansible works by connecting to machines over SSH and that is disabled by default in Raspbian. Take note of your IP address so you can connect later. It will be displayed on the screen. To do this run the command:

sudo systemctl start ssh

Then exit, everything else can be done from the Ansible machine.

From the machine you will be running Ansible

You will need to clone the git repo by typing in:

$ git clone

You need to generate and SSH key and install your public key. This is a great guide since that is beyond the scope of this tutorial. In this example will be using a ed25519 key and my raspberry pi host is at The hostname in the example code used is onion1, more can be added to the hosts file, but for now that is what I will be using in any examples.

To prepare your SSH client add with the above examples I add the following to my ssh client configuration located at ~/.ssh/config:

Host onion1
  User pi
  IdentityFile ~/.ssh/id_ed25519

After that to run the anible playbook, run it with:

$ ansible-playbook -i hosts site.yml


  • Random MAC address on the onion-router nodes that survive playbook runs
  • Make it run on Debian Stretch regular, not just Raspbian Working as of 4/21/2018
  • Make it run on Ubuntu Done 4/21/2018
  • Make it run on CentOS
  • Set Hostname from variables in host_vars Done 4/21/2018
  • Provision private bridges
  • More thurough tutorial