Hyperboriarch

Hyperboriarch is a set of Ansible playbooks for installing, configuring, and maintaining Project Meshnet's cjdns routing software on Arch Linux hosts. It can also perform the basic tasks necessary to safeguard a freshly installed server, so you can go from nothing to a relatively secure cjdns node in no time flat. Welcome to Hyperboria!

If you're new to the project and looking to get connected to the network, first you'll need to find a peer.

Overview

If you apply the entire site.yml playbook to your hosts, the following tasks will be handled for you by the "common" role:

• an updated pacman mirrorlist will be downloaded
• an non-root administrative user will be created
• OpenSSH will be configured more securely
• basic ingress firewall rules will be put into place
• kernel parameters will be set to harden the network stack
• the Network Time Protocol (NTP) service will be configured
• vnStat will be installed to monitor network traffic usage

...and the following tasks will be handled by the "cjdns" role:

• cjdns and (optionally) cjdcmd will be built and installed from the latest upstream git revision
• a host specific cjdroute.conf file will be copied over from the controlling machine

There are a lot of little conveniences automatically handled for you as well. For instance, the mirrorlist will only be updated on the initial run, the firewall will open up your cjdns port if it finds a valid cdjroute.conf file, cdjcmd will generate its required ~/.cjdadmin file, etc..

Note that you don't have to apply all of these tasks; everything is tagged for flexibility.

Initial Setup

$ git clone https://github.com/elasticdog/hyperboriarch.git
$ cd hyperboriarch/

Prerequisites

• Ansible v1.3+
• Arch Linux host(s)
• root-level access on the host(s), directly or via sudo
• an inventory file

For the inventory hosts file, it's easiest to keep it in the same directory as Hyperboriarch so Ansible can find the correct group_vars. Either set the ANSIBLE_HOSTS environment variable to point to its full path, or use the -i <inventory file> flag on all of your Ansible commands.

Bootstrapping

Arch Linux doesn’t have Python v2 installed by default, which is a dependency for Ansible. Luckily we can use the raw module to fix that:

For the bootstrapping instructions, I'm assuming that you can connect to your hosts as the root user...adjust these commands as necessary.

$ ansible all -m raw -a '/usr/bin/pacman -Sy --noconfirm python2' --user=root

Always having to specify the user can get annoying, and using root directly isn't the most secure practice. Instead we can create a new administrative user based on your current username and ssh key by running just the "bootstrap" tagged tasks from the playbook:

$ ansible-playbook site.yml --tags=bootstrap --user=root

Now you should be able to connect as yourself for all future tasks:

$ ansible all -m ping

cjdroute.conf

The last thing we need to worry about is the /etc/cjdroute.conf file that cjdns needs in order to run. It should be unique per host and contains your cryptographic key pair and network peering data.

Use an Existing Config

If you already have a cjdroute.conf file, simply copy it to the expected location on the controlling machine and Ansible will push it to the proper host:

$ cp <path-to>/cjdroute.conf roles/cjdns/files/{{ inventory_hostname }}-cjdroute.conf

As a concrete example, let's say you're managing a host "alice.example.com", and you have a cjdroute.conf file for it in your home directory:

$ cp ~/cjdroute.conf roles/cjdns/files/alice.example.com-cjdroute.conf
$ ansible-playbook site.yml

Generate a New Config

If you're starting from scratch, you can generate a config with the cjdroute command on the managed host(s) after you've done your first playbook run (expect a failure):

$ ansible-playbook site.yml
...
FATAL: all hosts have already failed -- aborting
...
$ ansible all -m shell -a "[[ -f /etc/cjdroute.conf ]] || /usr/bin/cjdroute --genconf > /tmp/cjdroute.conf"
$ ansible all -m fetch -a "src=/tmp/cjdroute.conf dest=roles/cjdns/files/{{ inventory_hostname }}-cjdroute.conf flat=yes"
$ ansible-playbook site.yml

Firewall Considerations

At this point, cjdns should be up and running on your host(s), but it will still have incoming connections blocked by the firewall. Now that we've pushed a cjdroute.conf file, Hyperboriarch can determine which port needs to be opened up. Run the "iptables" tagged tasks one final time to make the change:

$ ansible-playbook site.yml --tags=iptables

Only cjdns and ssh (TCP port 22) are allowed through the firewall out of the box, so you'll have to update the appropriate templates if you want to expose other services.

Updating cjdns

The cjdns project is alpha software and still under heavy development, so it's best to keep up-to-date with all of the upstream changes. You can easily rebuild the latest version and upgrade your systems by running the "cjdns" tagged tasks:

$ ansible-playbook site.yml --tags=cjdns

Playbook Options

Most of the tasks performed by Hyperboriarch can be customized by setting the value of particular variables. The default values for these variables are set and documented in the group_vars/all file on the controlling machine.

If you just want to override the values for a single run, you can use the --extra-vars flag:

$ ansible-playbook site.yml --extra-vars="update_mirrorlist=true"

License

Hyperboriarch is provided under the terms of the ISC License.

Copyright © 2013–2014, Aaron Bull Schaefer.