Ansible Role - WireGuard Site-to-Site VPN

This role sets up site-to-site VPNs using WireGuard.

If you appreciate this work, you can buy me a coffee.

Test Status Badges

• Molecule Status
• YamlLint Status
• PyLint Status
• Ansible-Lint Status
• Ansible Galaxy

Molecule logs are available: Short, Full.

Tested on:

• Debian 11
• Raspbian 11
• Debian 12

Installation

You can install the role via the command line:

# latest version
ansible-galaxy role install git+https://github.com/ansibleguy/infra_wireguard

# from Ansible Galaxy
ansible-galaxy install ansibleguy.infra_wireguard

# or specify a custom role path
ansible-galaxy install ansibleguy.infra_wireguard --roles-path ./roles

# install dependencies
ansible-galaxy install -r requirements.yml
python3 -m pip install -r requirements.txt

Contributing

You can:

• Open Pull Requests
• Start discussions
• Report issues (after checking the troubleshooting guide below)

Usage

If you're looking for a simple Ansible GUI, check out my Ansible WebUI.

Examples

Here are some configuration examples and results:

• Single Topology
• Star Topology
• Mesh Topology

Configuration

Define your WireGuard topologies across multiple hosts. The role will configure only the topologies related to the target hosts' names.

wireguard:
  restart_on_change: true  # restart services on changes

  topologies:
    dc_nl:
      type: 'single'
      peers:
        srv02:
          Endpoint: 'srv02.wg.template.ansibleguy.net'
          Address: '10.100.0.1/30'

        srv03:
          Endpoint: 'srv03.wg.template.ansibleguy.net'
          Address: '10.100.0.2/30'

You can use 'ansible-vault' to encrypt host-key files:

ansible-vault encrypt roles/ansibleguy.infra_wireguard/files/keys/some_file.key

Execution

Run the playbook:

ansible-playbook -K -D -i inventory/hosts.yml playbook.yml

If you encrypted your keys, run:

ansible-playbook -K -D -i inventory/hosts.yml playbook.yml --ask-vault-pass

Useful tags are available:

• base
• config
• tunnels
• purge

If you want to provision one specific topology, set the variable during execution:

ansible-playbook -K -D -i inventory/hosts.yml playbook.yml -e only_topo=TOPOLOGY_KEY

Functionality

• Package Installation: WireGuard and Resolvconf for name resolution.
• Configuration: Simplified by defining topologies.
  • Supported topologies:
    • Single: Connect two nodes.
    • Star: Multiple nodes connect to one central hub.
    • Mesh: Each peer connects to every other peer.
• Key Management: Generates unique keys for each host.
• Routing: You manage routing. Optional auto-added WG routes available.
• Defaults: Saves private keys, disables auto-routing, enables logging, restarts service on changes.
• Opt-in/Opt-out features:
  • Using PSK for security.
  • Purging orphaned tunnels.
  • Not installing 'resolvconf' for DNS resolution.
  • Not enabling traffic forwarding.

Info

• This role only supports Debian-based systems.
• Many functions can be opted in or out. See options in main defaults file.
• Not every setting is validated, so check configurations carefully.
• Ensure WireGuard scripts are planned properly for routing and metrics.
• Keep topology names short and simple (no special characters).
• Keys are saved in the 'files' directory by default.

Troubleshooting

If you face issues, follow these steps:

1. Check if the VPN is active

wg show all

If not:

• Connection may be misconfigured or blocked by firewall.
• Check WireGuard logs for errors.

2. Check traffic over the tunnel

Ping the remote WireGuard IP:

ping 10.0.1.2 -I 10.0.1.1

If not:

• Ensure the tunnel is running and keys match on both sides.

3. Check traffic routing

Try to ping an IP from the remote subnet:

ping 172.30.1.1 -I 172.20.0.1

4. Still have issues?

If you're experiencing problems after these checks, consider submitting an issue on GitHub with your troubleshooting results.