How to Automate Your VPN Setup With Ansible

In a previous blogpost, we set up a WireGuard VPN server and client and learned about various configuration options for WireGuard, how to improve VPN server uptime, how to relay traffic, and more. Setting up a server and client like that is a lot of work! If the server dies or you want to set up a new server (maybe for a friend or family member this time), you have to go back to the walk-through and follow all the steps, remembering if you deviated from those instructions at any point.

There's a better way — automation! If you're only going to do a thing once (e.g. set up a VPN), investing in automation probably doesn't make sense. But if you anticipate doing a thing repeatedly, automating it frees up your time to learn and accomplish more in the future. You can also share your automation, empowering others to build and achieve more, faster.

Automation is the heart of computing, and many different automation tools and approaches have sprung up over time. For our project of automating VPN server setup, we can consider a variety of tools:

• Shell scripts
  The simplest approach from a tooling perspective, writing shell scripts would involve running the commands from the previous WireGuard tutorial blogpost, using ssh for the commands that run on the server and 

  rsync

   to copy configurations files to the server.
• SSH scripting libraries like Capistrano or Fabric
  If shell scripting isn't ideal, there are libraries that expose similar scripting functionality in a more ergonomic interface for developers familiar with higher-level languages like Ruby and Python.
• Infrastructure/configuration automation tools like Puppet, Chef, or Ansible
  Tools in this category are even more specialized for automating server infrastructure and configuration, often including an ecosystem of packages and plugins to automatically set up or configure nearly anything you can think of.
• Infrastructure-as-code tools like Terraform
  Infrastructure-as-code (IaC) tools have a lot of overlap with the above category, but support provisioning cloud resources in a more first-class/native way.
• Containers like Docker
  You could also run WireGuard in containers, deploying a server-configured container image to a cloud provider and running a client-configured container image locally to connect to the server. There are a few existing examples of this approach.

For this tutorial, I'm going to focus on the middle category above — infrastructure / configuration automation tools — and specifically, I'll focus on Ansible. There is a great comparison of different tools in this area by Gruntwork and, even though that article favors Terraform, Ansible is still a useful general-purpose tool, especially if you're working with servers that aren't "in the cloud", such as a Raspberry Pi at home.

Let's get started with automating VPN setup with Ansible! By the end of this article, we'll be able to set up a VPN server and client with a single command. Similar to the previous blogpost, I'll use Ubuntu 20.04 and DigitalOcean droplets.

Setting Up Ansible

Ansible can be installed via an OS package manager like 

apt

pip

pyenv

pyenv

# From https://github.com/pyenv/pyenv/wiki#suggested-build-environment
sudo apt-get update

sudo apt-get install --no-install-recommends make build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev

curl https://pyenv.run | bash

It's a good habit when a tutorial gives you 

curl <url> | bash

~/.pyenv

Follow the output prompt from above, which asks you to put lines like the below in your shell initialization script (e.g. 

~/.bashrc

export PATH="/home/YOUR_USERNAME/.pyenv/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"

Install a recent python version:

# List available python versions
pyenv install --list

# Install a specific version
pyenv install 3.9.2

# (Suggested) If you want to always use that version when running `python`
# in your terminal
pyenv global 3.9.2

If you want, you can also create a virtualenv to further isolate the Ansible installation, and make that virtualenv automatically activate when you're in a particular folder/repo. That would look like:

# (Optional)

# Feel free to pick a different virtualenv name than "ansible-tutorial"
pyenv virtualenv 3.9.2 ansible-tutorial

# Create a .python-version file that pyenv will find when your shell is in the 
# same directory (or a sub-directory) and automatically activate the named
# virtualenv
pyenv local ansible-tutorial

Install the 

ansible

ansible-playbook

pip install ansible

# Confirm installation worked
ansible --version

Get a Server

To use Ansible for a VPN server, we need… a server! Ansible could provision a server from a cloud provider for us (and I'll touch on this briefly later), but we'll keep our playbook hardware-provider-agnostic for now, so you can run it as easily against a cloud server as a Raspberry Pi on your home network. I'm going to create a $5/month DigitalOcean droplet to test against, but you could also use Vagrant (to test against a local VM) or any server you can SSH to.

Testing Ansible playbooks against VMs, rather than a bare-metal machine, comes with an advantage — after you've written the playbook, you can start a new, empty VM and test the whole playbook start to finish to ensure that it works consistently.

Connecting to the Server with Ansible

Once you have your server or VM, take note of its IP address use it to create an 

inventory.ini

[vpn]
vpn_server ansible_host=203.0.113.1 ansible_user=root

An inventory file tells Ansible what servers it can act upon and how to access them. Let's use the above inventory file as an example. When we run Ansible and target the 

vpn

vpn_server

ssh root@203.0.113.1

So, if you can't SSH to the server, then Ansible won't be able to connect either!

Connecting to the server with an SSH key is strongly recommended! Add your SSH key to your server to connect without needing a password. If you must connect with a password, you can 

sudo apt install sshpass

--ask-pass

Let's test to make sure that Ansible can connect to the server:

ansible -i inventory.ini -m ping vpn

This runs the ping Ansible module, targeting the 

vpn

Ansible's Built-in Variables and Facts

There are other useful Ansible modules that we can use with the

ansible

• The setup module fetches system information, also known as "facts", about the server. You can use these facts as variables in Ansible commands and playbooks.
• The debug module can evaluate variables, which is useful for… well, debugging!

Try running both of these modules with your server so you can see what facts and information Ansible makes available:

ansible -i inventory.ini -m setup vpn
ansible -i inventory.ini -m debug -a "var=hostvars" vpn

This was one of the most confusing parts for me when learning Ansible — figuring out what all these built-in variables and facts (like 

groups

inventory_dir

ansible_distribution

Writing an Ansible Playbook

The 

ansible

ansible

ansible-playbook

Let's write a 

playbook.yml

inventory.ini

---
- name: setup vpn server
  hosts: vpn_server
  tasks:
  - name: ping
    ping:
  - name: show variables and facts
    debug: var=hostvars

If you're not familiar with YAML, the above is equivalent to this JSON structure:

[{'name': 'setup vpn server',
  'hosts': 'vpn_server',
  'tasks': [{'name': 'ping', 'ping': None},
            {'name': 'show variables and facts', 'debug': 'var=hostvars'}]}]

Breaking down the above:

• The top-level structure is a "play" in Ansible lexicon. Our play above has a 

  name

  , a 

  hosts

  pattern which describes which servers the play will run against, and a list of 

  tasks

  .
• We have 2 tasks, each has a 

  name

   and the name of an Ansible module that will do something.

Run the playbook...

ansible-playbook -i inventory.ini playbook.yml

… and you'll see that it gathers facts from the server (just like the 

ansible -m

vpn_server

There are tons of built-in Ansible modules, even more curated Ansible community modules, and even more published to Ansible Galaxy (an open repository for Ansible collections and roles).

WireGuard Server Setup

There's much more to learn about Ansible! But let's stop here and apply what we've learned in order to set up a WireGuard server.

Referring to the steps we took in the previous tutorial, we want to:

1. Install the 

   wireguard

    system package
2. Create public and private keys with correct permissions
3. Create the server's WireGuard configuration file
4. (Optionally) Enable IP forwarding for relaying traffic
5. Start the VPN

Managing the Keys

As hinted at in the previous tutorial, if we want to repeatably deploy the VPN server without needing to reconfigure all VPN clients, we need to use the same private key every time.

Put another way: if we generated a private key while deploying the server and used the corresponding public key on various clients, and the server ends up dying, we could deploy it again by generating a new private key. However, all of our VPN clients would then need to update to the new public key to be able to connect to the new VPN server. This would be inconvenient!

Instead, we'll generate the server keys once by hand and use them in the playbook so they're consistent between every deploy. This means we won't include step #2 from above in the Ansible playbook.

Generate the keys with 

wg genkey

wg pubkey

privkey=$(wg genkey) sh -c 'echo "
    server_privkey: $privkey
    server_pubkey: $(echo $privkey | wg pubkey)"'

Copy the output lines and add them to a new 

vars

playbook.yml

---
- name: setup vpn server
  hosts: vpn_server
  vars:
    server_privkey: aBYk1JZyP8ck+FeaTjb3xi94U4Nv8V+gWoTW1hRLQlo=
    server_pubkey: 7/6f7bUT+2hWMEP5BxeK51PGuMuTnQ9pRpkxg5jUSTo=
  tasks:
  # ...

Encrypting the Private Key

It's a good practice to AVOID having secrets in plaintext (like the VPN private key above). This is especially true if those secrets will be shared with anyone else, like via a git repo. Let's prevent this by using Ansible Vault. Vault is a tool for encrypting secret values and using them in playbooks. Encrypt the private key with:

ansible-vault encrypt_string --ask-vault-password --stdin-name server_privkey

You'll be prompted twice for a Vault encryption password, after which you'll paste your 

privkey

Ctrl+d

Ctrl+d

privkey

---
- name: setup vpn server
  hosts: vpn_server
  vars:
    server_privkey: !vault |
          $ANSIBLE_VAULT;1.1;AES256
          646438636565343063343631326136386239623935393637336539653636386135363
          663386639393232346534643163656363316234306439306566306534610a31326664
          363763663139383034636632343230376365333130333230373866353033326563303
          5636138373830633534373033303536303566663166616539360a3936353033663263
          336662663034376661616631343661333164363134373061343739633637623739306
          465653532383838393662396333623966343165366635353132396332313762343534
          65313761623964653532623839356633343838
    server_pubkey: 7/6f7bUT+2hWMEP5BxeK51PGuMuTnQ9pRpkxg5jUSTo=
  tasks:
  ...

Make sure to remember your encryption password (and save it in a password manager); you'll need to enter it every time you run the playbook.

Installing and Configuring WireGuard

Next, we'll remove our testing 

ping

debug

playbook.yml

---
- name: setup vpn server
  hosts: vpn_server
  vars:
    server_privkey: !vault |
          $ANSIBLE_VAULT;1.1;AES256
          646438636565343063343631326136386239623935393637336539653636386135363
          663386639393232346534643163656363316234306439306566306534610a31326664
          363763663139383034636632343230376365333130333230373866353033326563303
          5636138373830633534373033303536303566663166616539360a3936353033663263
          336662663034376661616631343661333164363134373061343739633637623739306
          465653532383838393662396333623966343165366635353132396332313762343534
          65313761623964653532623839356633343838
    server_pubkey: 7/6f7bUT+2hWMEP5BxeK51PGuMuTnQ9pRpkxg5jUSTo=
  tasks:
  # https://docs.ansible.com/ansible/latest/collections/ansible/builtin/apt_module.html
  - name: install wireguard package
    apt:
      name: wireguard
      state: present
      update_cache: yes

  # https://docs.ansible.com/ansible/latest/collections/ansible/builtin/copy_module.html
  - name: create server wireguard config
    template:
      dest: /etc/wireguard/wg0.conf
      src: server_wg0.conf.j2
      owner: root
      group: root
      mode: '0600'

  # https://docs.ansible.com/ansible/latest/collections/ansible/posix/sysctl_module.html
  - name: enable and persist ip forwarding
    sysctl:
      name: net.ipv4.ip_forward
      value: "1"
      state: present
      sysctl_set: yes
      reload: yes

  # https://docs.ansible.com/ansible/latest/collections/ansible/builtin/systemd_module.html
  - name: start wireguard and enable on boot
    systemd:
      name: wg-quick@wg0
      enabled: yes
      state: started

Ok ok, yes, this is a bit like drawing an owl.

Source 

…but usually an ansible playbook like the above can be written quickly. I follow a cycle:

1. Type "ansible module install package" into a search engine
2. Open the docs.ansible.com result that looks most helpful
3. Read through available parameters and the (often helpful) examples at the bottom
4. Copy an example into my playbook and modify parameters as needed
5. Go back to step 1, searching for the next task (e.g. "ansible module template file")

I've included a comment line linking to the Ansible docs page for each module used in the 

playbook.yml

Testing our First Attempt

Let's test our playbook.

$ ansible-playbook -i inventory.ini --ask-vault-password playbook.yml
Vault password: 

PLAY [setup vpn server] ********************************************************

TASK [Gathering Facts] *********************************************************
ok: [vpn_server]

TASK [install wireguard package] ***********************************************
changed: [vpn_server]

TASK [create server wireguard config] ******************************************
fatal: [vpn_server]: FAILED! => {"changed": false, "msg": "Could not find or access 'server_wg0.conf.j2'\nSearched in: ..."}

PLAY RECAP *********************************************************************
vpn_server                 : ok=2    changed=1    unreachable=0    failed=1    skipped=0    rescued=0    ignored=0

Oh no!

Installing WireGuard was successful, but creating the config failed. Ansible's error messages are usually helpful, and this one indicates that the template file (

server_wg0.conf.j2

Let's create it at

templates/server_wg0.conf.j2

# {{ ansible_managed }}
[Interface]
Address = 10.0.1.1/24
ListenPort = 51820
PrivateKey = {{ server_privkey }}

A few notes about the above:

• Ansible automatically searches in relative paths like 

  templates/

   and 

  files/

   when running Ansible modules that have a 

  src

   parameter. Our 

  template

   task has a parameter 

  src: server_wg0.conf.j2

  , so Ansible will search for it in the 

  templates/

  folder.
• It's convention to suffix template files with 

  .j2

  , to indicate that the file will be templated with Jinja2.
• In Jinja2, values inside double curly braces (

  {{ variable }}

  ) will be replaced with the value of the variable. In this template, the 

  server_privkey

   variable will be decrypted and its value inserted into the resulting file in place of 

  {{ server_privkey }}

  .
• The 

  {{ ansible_managed }}

   text is replaced with the string "Ansible managed". It's a good convention to put this in a comment at the top of templated files, because it signals to anyone reading the file on the server that the file is managed by Ansible — any edits they make could be overwritten when Ansible next runs, so they should find and make edits in the corresponding Ansible playbook and template files instead.

Let's run the test again:

$ ansible-playbook -i inventory.ini --ask-vault-password playbook.yml
Vault password: 

PLAY [setup vpn server] ********************************************************

TASK [Gathering Facts] *********************************************************
ok: [vpn_server]

TASK [install wireguard package] ***********************************************
ok: [vpn_server]

TASK [create server wireguard config] ******************************************
changed: [vpn_server]

TASK [enable and persist ip forwarding] ****************************************
changed: [vpn_server]

TASK [start wireguard and enable on boot] **************************************
changed: [vpn_server]

PLAY RECAP *********************************************************************
vpn_server                 : ok=5    changed=3    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

It succeeded!

The WireGuard interface is now running on the server.

Notice that the "install wireguard package" step shows 

ok

changed

apt

wireguard

state=present

WireGuard Client Setup

Ansible can also operate on the local machine. To set up our local machine as a client, we want to:

1. Install the 

   wireguard

    system package
2. Create public and private keys with correct permissions
3. Create the client's WireGuard configuration file, which must include the server's public key
4. Start the VPN

We also need to update the server's configuration file with a 

[Peer]

Acting on Localhost

Because we're targeting a new host (

localhost

playbook.yml

vpn_server

---
- name: setup vpn client
  hosts: localhost
  connection: local
  become: yes
  vars:
    # Use system python so apt package is available
    ansible_python_interpreter: "/usr/bin/env python"
  tasks:
    # Coming soon

- name: setup vpn server
  hosts: vpn
  # Rest of server vars/tasks here...

Lots of new things here!

• We target the local machine with using 

  [localhost](http://localhost)

   for the hosts pattern.
• We "connect" locally by using the 

  local

   connection plugin.
• The 

  become: yes

   line indicates that the play will run as root, which we need to be able to install the 

  wireguard

   package. Ansible will effectively run 

  sudo apt-get install wireguard

  , rather than just 

  apt-get install wireguard

   (which would fail). Because of this setting, we'll need to run the playbook with the 

  --ask-become-pass

   flag. We didn't need this line for the server setup play, because we're already connecting as root via the

  ansible_user=root

   connection variable.
• With the 

  ansible_python_interpreter

   var, we tell Ansible to use the system python (which includes the 

  apt

   python package). Alternatively, we could install that package for our current python 3.9.2 installation. If you get a 

  No such file or directory

   error, you may need to change the line from 

  python

   to 

  python3

  .

Client Setup Tasks and Config

Writing the Ansible tasks for the client-side VPN setup is similar to the server side.

---
- name: setup vpn clients
  hosts: localhost
  connection: local
  become: yes
  vars:
    # Use system python so apt package is available
    ansible_python_interpreter: "/usr/bin/env python"
  tasks:
  - name: install wireguard package
    apt:
      name: wireguard
      state: present
      update_cache: yes

  - name: generate private key
    shell:
      cmd: umask 077 && wg genkey | tee privatekey | wg pubkey > publickey
      chdir: /etc/wireguard
      creates: /etc/wireguard/publickey

  - name: get public key
    command: cat /etc/wireguard/publickey
    register: publickey_contents
    changed_when: False

  # Save pubkey as a fact, so we can use it to template wg0.conf for the server
  - name: set public key fact
    set_fact:
      pubkey: "{{ publickey_contents.stdout }}"

  - name: create client wireguard config
    template:
      dest: /etc/wireguard/wg0.conf
      src: client_wg0.conf.j2
      owner: root
      group: root
      mode: '0600'

- name: setup vpn server
  hosts: vpn_server
  # Rest of server vars/tasks here...

Breaking this down:

• Installing the 

  wireguard

   package should look very familiar!
• We generate keys with the 

  shell

   module so we can use pipes and file redirection. The keys are only generated if the 

  publickey

   file doesn't already exist, thanks to the 

  creates

  parameter.
• Next, we need to save the public key so we can add it as a 

  [Peer]

   section in the server config. Normally, we'd use 

  {{ lookup('file', '/etc/wireguard/publickey') }}

   to look up a value from a file, but the file lookup modules seems not to respect 

  become: yes

  ; it tries to read the file without escalating to root privileges and fails as a result. So, we instead

  cat

   the file and save the resulting output as a fact.
• Finally, template the client config file. Its contents closely match the previous tutorial's, but we use the 

  ansible_host

   IP address of the VPN server from 

  inventory.ini

   to set the server's endpoint.

[Interface]
# The address your computer will use on the VPN
Address = 10.0.0.8/32

# Load your privatekey from file
PostUp = wg set %i private-key /etc/wireguard/privatekey
# Also ping the vpn server to ensure the tunnel is initialized
PostUp = ping -c1 10.0.0.1

[Peer]
# VPN server's wireguard public key
PublicKey = {{ server_pubkey }}

# Public IP address of your VPN server (USE YOURS!)
# Use the floating IP address if you created one for your VPN server
Endpoint = {{ hostvars['vpn_server'].ansible_host }}:51820

# 10.0.0.0/24 is the VPN subnet
AllowedIPs = 10.0.0.0/24

# To also accept and send traffic to a VPC subnet at 10.110.0.0/20
# AllowedIPs = 10.0.0.0/24,10.110.0.0/20

# To accept traffic from and send traffic to any IP address through the VPN
# AllowedIPs = 0.0.0.0/0

# To keep a connection open from the server to this client
# (Use if you're behind a NAT, e.g. on a home network, and
# want peers to be able to connect to you.)
# PersistentKeepalive = 25

Managing Variables

If we run the playbook now, it will fail with a 

'server_pubkey' is undefined

server_pubkey

group_vars/

group_vars/vpn.yml

vpn

localhost

vpn

group_vars/all.yml

Move the server keys' variables from 

playbook.yml

group_vars.all.yml

---
server_privkey: !vault |
      $ANSIBLE_VAULT;1.1;AES256
      646438636565343063343631326136386239623935393637336539653636386135363
      663386639393232346534643163656363316234306439306566306534610a31326664
      363763663139383034636632343230376365333130333230373866353033326563303
      5636138373830633534373033303536303566663166616539360a3936353033663263
      336662663034376661616631343661333164363134373061343739633637623739306
      465653532383838393662396333623966343165366635353132396332313762343534
      65313761623964653532623839356633343838
server_pubkey: 7/6f7bUT+2hWMEP5BxeK51PGuMuTnQ9pRpkxg5jUSTo=

Your directory should now look like this:

.
├── group_vars
│   ├── all.yml
├── inventory.ini
├── playbook.yml
└── templates
    ├── client_wg0.conf.j2
    └── server_wg0.conf.j2

Run the playbook and the client should run all its tasks successfully:

ansible-playbook -i inventory.ini --ask-vault-password --ask-become-pass playbook.yml

The VPN client is now set up. The only remaining step for the client is to start the VPN after the server is running and configured to accept connections from the client (so the client's 

PostUp

Adding a Peer to the Server Config

Add a 

[Peer]

templates/server_wg0.conf.j2

# {{ ansible_managed }}
[Interface]
Address = 10.0.0.1/24
ListenPort = 51820
PrivateKey = {{ server_privkey }}

[Peer]
PublicKey = {{ hostvars['localhost'].pubkey }}
AllowedIPs = 10.0.0.8

We read the 

{{ server_privkey }}

group_vars/all.yml

{{ hostvars['localhost'].pubkey }}

set_fact

Reloading the Server Config

If we run the playbook, the config file on the server will be updated with the new 

[Peer]

handlers

tasks

playbook.yml

create client wireguard config

create server wireguard config

# ...
  - name: create client wireguard config
    template:
      dest: /etc/wireguard/wg0.conf
      src: client_wg0.conf.j2
      owner: root
      group: root
      mode: '0600'
    notify: restart wireguard

  handlers:
  # Restarts WireGuard interface, loading any new config and running PostUp
  # commands in the process. Notify this handler on client config changes.
  - name: restart wireguard
    shell: wg-quick down wg0; wg-quick up wg0
    args:
      executable: /bin/bash

- name: setup vpn server
  hosts: vpn_server
  tasks:
  # ...
  - name: create server wireguard config
    template:
      dest: /etc/wireguard/wg0.conf
      src: wg0.conf.j2
      owner: root
      group: root
      mode: '0600'
    notify: reload wireguard config
  # ...

  handlers:
  # Reloads config without disrupting current peer sessions, but does not
  # re-run PostUp commands. Notify this handler on server config changes.
  - name: reload wireguard config
    shell: wg syncconf wg0 <(wg-quick strip wg0)
    args:
      executable: /bin/bash
# ...

The 

template

Start the VPN Client

Add one final play to the end of the playbook to start the client VPN now that the server is configured to accept its connection:

# ...
- name: start vpn on clients
  hosts: localhost
  connection: local
  become: yes
  tasks:
  - name: start vpn
    command: wg-quick up wg0

Automation Complete!

Now we can run the whole playbook and — whether the server and client are brand-new or in some intermediate state — this single command will set up a WireGuard VPN server and client!

ansible-playbook -i inventory.ini --ask-vault-password --ask-become-pass playbook.yml

The complete Ansible code can be found at: https://gitlab.com/tangram-vision-oss/tangram-visions-blog/-/tree/main/AnsibleVpnSetup

There are many improvements that could be made:

• Provision a cloud server automatically, using an Ansible module such as community.digitalocean.digital_ocean_droplet.
• Automatically update a floating IP address when provisioning a new cloud VPN server.
• Configure multiple clients automatically. One approach is to add a 

  vpn_clients

   group to the inventory, define VPN IPs in the inventory (e.g. 

  vpn_ip=10.0.0.8

  ), and use those host variables in the config templates. When templating the server config, loop over hostnames in the clients group, adding a new 

  [Peer]

   block for each.
• Organize the playbook as roles, one for the server and one for the client. Roles are more reusable and shareable than playbooks.
• Test and lint with molecule and ansible-lint.

Thanks for joining me on this Ansible-learning journey! If you have any suggestions or corrections, please let me know or send us a tweet, and if you’re curious to learn more about how we improve perception sensors, visit us at Tangram Vision.

Previously published here.