githubixx.ansible_role_wireguard

<!--
Copyright (C) 2018-2023 Robert Wimmer
Copyright (C) 2019 fbourqui
SPDX-License-Identifier: GPL-3.0-or-later
-->

# Ansible Role for WireGuard

This Ansible role is featured in my blog series [Kubernetes the not so hard way with Ansible](https://www.tauceti.blog/post/kubernetes-the-not-so-hard-way-with-ansible-wireguard/), but it can also be used on its own. I use WireGuard and this Ansible role to create a secure VPN that connects all nodes in my Kubernetes cluster.

WireGuard is a VPN (Virtual Private Network) that works with both IPv4 and IPv6 using the UDP protocol. If you want to learn more about WireGuard, check out this guide: [Installing WireGuard, the Modern VPN](https://research.kudelskisecurity.com/2017/06/07/installing-wireguard-the-modern-vpn/).

## Supported Linux Distributions

This role works with:

- Ubuntu 20.04 (Focal Fossa)
- Ubuntu 22.04 (Jammy Jellyfish)
- Ubuntu 24.04 (Noble Numbat)
- Arch Linux
- Debian 11 (Bullseye)
- Debian 12 (Bookworm)
- Fedora 39
- AlmaLinux 9
- Rocky Linux 9
- openSUSE Leap 15.5
- openSUSE Leap 15.6
- Oracle Linux 9

### Best Effort Support

- AlmaLinux 8
- Rocky Linux 8
- elementary OS 6
- CentOS 7 (end of life after June 2024)

Molecule tests are [available](https://github.com/githubixx/ansible-role-wireguard#testing) (details below). It should work with `Raspbian Buster`, but no tests are available for this. MacOS has partial support, but it's only best effort.

## MacOS Instructions

This playbook sets up a `systemd` service on Linux automatically. For MacOS, it installs the necessary packages and generates the `wg0.conf` file, defaulting to `/opt/local/etc/wireguard`. To start the VPN, run:

```bash
sudo wg-quick up wg0

To stop it, use:

sudo wg-quick down wg0

You can also install the official app and import the wg0.conf file.

Versioning

I use semantic versioning for releases. Check out the latest tag for stable versions, while the master branch is used for development.

Requirements

By default, port 51820 (UDP) must be open for outside access. You can change this by modifying the wireguard_port variable. Additionally, IP forwarding should be enabled, like so: echo 1 > /proc/sys/net/ipv4/ip_forward. This role does not cover enabling IP forwarding, as I believe it's best done separately.

You may use my ansible-role-harden-linux for added security features. The PreUp, PreDown, PostUp, and PostDown hooks are good for executing network setup before starting or stopping a WireGuard interface.

Changelog

Change History:

See full CHANGELOG.md

Recent Changes:

17.0.0

• BREAKING: Removed support for openSUSE 15.4 (end of life)
• FEATURE: Added support for Ubuntu 24.04 and openSUSE 15.6
• MOLECULE: Removed outdated Proxmox code and replaced Vagrant box for Rocky Linux. Updated Molecule tests.

Installation

To install, you can:

• Clone the GitHub repository:

git clone https://github.com/githubixx/ansible-role-wireguard.git githubixx.ansible_role_wireguard

• Use ansible-galaxy to download directly from Ansible Galaxy:

ansible-galaxy role install githubixx.ansible_role_wireguard

• Create a requirements.yml file and install with:

---
roles:
  - name: githubixx.ansible_role_wireguard
    src: https://github.com/githubixx/ansible-role-wireguard.git
    version: 17.0.0

Run:

ansible-galaxy role install -r requirements.yml

Role Variables

You can customize the following variables:

# Directory for WireGuard config on remote hosts
wireguard_remote_directory: "/etc/wireguard" # For Linux
# wireguard_remote_directory: "/opt/local/etc/wireguard" # For MacOS

# Default listening port for WireGuard
wireguard_port: "51820"

# Default interface name (wg0)
wireguard_interface: "wg0"

# Owner and group for the wg.conf file
wireguard_conf_owner: root
wireguard_conf_group: "{{ 'root' if not ansible_os_family == 'Darwin' else 'wheel' }}"

# File permissions for wg.conf
wireguard_conf_mode: 0600

# Backup setting for wg.conf changes
wireguard_conf_backup: false

# WireGuard service state
wireguard_service_enabled: "yes"
wireguard_service_state: "started"

# Interface restart option
wireguard_interface_restart: false

# Optional: your own WireGuard private key (sensitive)
# wireguard_private_key:

# Cache update option for package manager
wireguard_update_cache: "true"

# Load WireGuard kernel module
wireguard_install_kernel_module: true

Each host in host_vars/ should specify an IP using wireguard_address or wireguard_addresses, for example:

wireguard_addresses:
  - "10.8.0.101/24"

Example Playbooks

Here are simple example playbooks:

- hosts: vpn
  roles:
    - githubixx.ansible_role_wireguard

- hosts: vpn
  roles:
    - role: githubixx.ansible_role_wireguard
      tags: role-wireguard

Testing

This role includes tests using Molecule, libvirt, and QEMU/KVM. See my blog post on Testing Ansible roles for setup instructions.

To test:

molecule converge

To run tests:

molecule verify

To clean up:

molecule destroy

License

This project is licensed under the GNU General Public License v3.0 or later.

Author Information

Visit my blog at http://www.tauceti.blog. ```