openwisp.wireguard_openwisp

ansible-wireguard-openwisp

This is an Ansible role that helps you install WireGuard along with scripts to manage it for OpenWISP. Once you set it up correctly with OpenWISP, you won’t have to manage WireGuard peers manually; OpenWISP will take care of that for you.

This role can also help you set up scripts for managing VXLAN over WireGuard tunnels.

It has been tested on Debian and Ubuntu.

IMPORTANT: It is highly recommended to use this on clean virtual machines or Linux containers.

Minimum Ansible version required: 2.10.

How to Install & Use

To install this role on your local machine, you can use ansible-galaxy:

ansible-galaxy install openwisp.wireguard_openwisp

Check the example playbook in the "Full Example Playbook with SSL certificate" section to get started quickly.

IMPORTANT: This role does not configure packet forwarding or add static/dynamic routes on your server.

Because routing varies greatly based on different needs, it’s up to the user to configure this according to their requirements. We might add default routing/forwarding configurations in the future if there is enough interest.

Full Example Playbook with SSL certificate

By default, the playbook creates a self-signed (untrusted) SSL certificate for the VPN endpoint. If you use an untrusted certificate, you'll need to disable SSL verification on OpenWISP (not recommended for production). You can set up your own trusted certificate by following the steps below.

First, set up a valid domain for your WireGuard VPN, so your inventory file (hosts) should look like this:

[openwisp2_wireguard]
wireguard.yourdomain.com

You must be able to add a DNS record for wireguard.yourdomain.com; you cannot replace it with an IP address.

After your domain is configured and DNS is set up, install the Ansible role geerlingguy.certbot:

ansible-galaxy install geerlingguy.certbot

Create your playbook.yml, which should look something like this:

- hosts: openwisp2_wireguard
  become: "{{ become | default('yes') }}"
  roles:
    - geerlingguy.certbot
    - openwisp.wireguard_openwisp
  vars:
    openwisp2_wireguard_controller_url: "https://openwisp.yourdomain.com"
    openwisp2_wireguard_vpn_uuid: "paste-vpn-uuid-here"
    openwisp2_wireguard_vpn_key: "paste-vpn-key-here"
    openwisp2_wireguard_flask_key: "paste-endpoint-auth-token"

    # SSL certificates
    openwisp2_wireguard_ssl_cert: "/etc/letsencrypt/live/{{ ansible_fqdn }}/fullchain.pem"
    openwisp2_wireguard_ssl_key: "/etc/letsencrypt/live/{{ ansible_fqdn }}/privkey.pem"

    # Certbot settings
    certbot_auto_renew_user: "user-to-renew-certs"
    certbot_auto_renew_minute: "20"
    certbot_auto_renew_hour: "5"
    certbot_create_if_missing: true
    certbot_create_standalone_stop_services: []
    certbot_certs:
      - email: "your-email"
        domains:
          - wireguard.yourdomain.com

Read the documentation for geerlingguy.certbot for more details on how to configure the certbot role.

To learn about all the Ansible variables offered by openwisp.wireguard_openwisp, check the "Role Variables" section.

Setting Up Multiple WireGuard Interfaces

Using this role, you can set up multiple WireGuard interfaces on the same machine, managed independently by OpenWISP. Make sure that the following role variables are unique for each playbook:

openwisp2_wireguard_path
openwisp2_wireguard_flask_port

Here’s an example playbook showing how to set up two WireGuard interfaces:

- name: Setup first WireGuard interface
  hosts:
    - wireguard
  become: "{{ become | default('yes') }}"
  roles:
    - openwisp.wireguard_openwisp
  vars:
    openwisp2_wireguard_controller_url: "https://openwisp.yourdomain.com"
    openwisp2_wireguard_path: "/opt/wireguard-openwisp/wireguard-1"
    openwisp2_wireguard_vpn_uuid: "paste-vpn1-uuid-here"
    openwisp2_wireguard_vpn_key: "paste-vpn1-key-here"
    openwisp2_wireguard_flask_key: "paste-vpn1-endpoint-auth-token"
    openwisp2_wireguard_flask_port: 8081

- name: Setup second WireGuard interface
  hosts:
    - wireguard
  become: "{{ become | default('yes') }}"
  roles:
    - openwisp.wireguard_openwisp
  vars:
    openwisp2_wireguard_controller_url: "https://openwisp.yourdomain.com"
    openwisp2_wireguard_path: "/opt/wireguard-openwisp/wireguard-2"
    openwisp2_wireguard_vpn_uuid: "paste-vpn-2-uuid-here"
    openwisp2_wireguard_vpn_key: "paste-vpn-2-key-here"
    openwisp2_wireguard_flask_key: "paste-vpn-2-endpoint-auth-token"
    openwisp2_wireguard_flask_port: 8082

Tips

When creating VPN server objects in OpenWISP, ensure that the interface name and port are unique for each VPN. Otherwise, the update scripts may run into conflicts and not function properly.

Role Variables

This role includes many customizable variables.

Here’s a list of all the variables you can modify (you might also want to look at the default values of these variables).

- hosts: openwisp2_wireguard
  become: "{{ become | default('yes') }}"
  roles:
    - openwisp.wireguard_openwisp
  vars:
    # URL of OpenWISP instance. Optional if WireGuard is on the same host.
    openwisp2_wireguard_controller_url: "https://openwisp.yourdomain.com"
    # Installation directory for scripts
    openwisp2_wireguard_path: "/opt/wireguard-openwisp"
    # For "insecure" SSL connections (recommended as false)
    openwisp2_wireguard_curl_insecure: false
    # VPN UUID from OpenWISP
    openwisp2_wireguard_vpn_uuid: "paste-vpn-uuid-here"
    # VPN key from OpenWISP
    openwisp2_wireguard_vpn_key: "paste-vpn-key-here"
    # Flask endpoint for updates
    openwisp2_wireguard_flask_endpoint: "/trigger-update"
    # Auth key for update endpoint
    openwisp2_wireguard_flask_key: "paste-endpoint-auth-token"
    # Flask endpoint port
    openwisp2_wireguard_flask_port: 8081
    # Flask host
    openwisp2_wireguard_flask_host: 0.0.0.0
    # Log level for Flask
    openwisp2_wireguard_logging_level: "WARNING"
    # Command to run uwsgi
    openwisp2_wireguard_uwsgi_command: "{{ openwisp2_wireguard_path }}/env/bin/uwsgi uwsgi.ini"

    # Paths for SSL certificate and key (self-signed will be generated if omitted)
    openwisp2_wireguard_ssl_cert: "/opt/wireguard-openwisp/ssl/server.crt"
    openwisp2_wireguard_ssl_key: "/opt/wireguard-openwisp/ssl/server.key"
    # Optional SSL certificate info
    openwisp2_wireguard_ssl_country: "US"
    openwisp2_wireguard_ssl_state: "California"
    openwisp2_wireguard_ssl_locality: "San Francisco"
    openwisp2_wireguard_ssl_organization: "IT dep."

    # Python version (default is python3, set to python2.7 for older systems)
    openwisp2_wireguard_python: python2.7
    # Virtualenv command for your distribution
    openwisp2_wireguard_virtualenv_command: "virtualenv"

    # VXLAN connection configuration
    openwisp2_wireguard_vxlan_ipv4_method: disabled
    openwisp2_wireguard_vxlan_ipv6_method: disabled

Troubleshooting

To manually trigger a configuration check, run:

sudo -u openwisp /opt/wireguard-openwisp/update_wireguard.sh check_config

You can find logs for the application that updates WireGuard configurations in the file located at /opt/wireguard-openwisp/vpn_updater.log.

Contributing

Please refer to the OpenWISP contributing guidelines.

How to Run Tests

If you want to contribute to ansible-wireguard-openwisp, make sure to run tests to verify your changes don't break anything.

Follow these steps:

Step 1: Clone the ansible-wireguard-openwisp repository:

git clone https://github.com/<your_fork>/ansible-wireguard-openwisp.git

Step 2: Install Docker

If you haven't installed Docker yet, you can install it on Debian/Ubuntu systems with:

sudo apt-get install docker.io

Step 3: Install Molecule and dependencies

pip install molecule[docker,ansible] yamllint ansible-lint docker

Step 4: Pull Docker images

docker pull geerlingguy/docker-ubuntu2204-ansible:latest
docker pull geerlingguy/docker-ubuntu2004-ansible:latest
docker pull geerlingguy/docker-debian11-ansible:latest

Step 5: Run tests with Molecule