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.