WireGuard

STATE: stable

TESTS: wireguard_server | wireguard_peer | wireguard_general | wireguard_show

API Docs: Plugin - Wireguard

Service Docs: WireGuard - Site to Site | WireGuard - Client to Site

Prerequisites

You need to install the WireGuard plugin:

os-wireguard

You can also install it using the package module.

Definition

For basic parameters see: Basics

ansibleguy.opnsense.wireguard_server

Parameter

Type

Required

Default value

Aliases

Comment

name

string

true

-

-

The unique name of the local WireGuard server instance

peers

list

false

-

clients

List of existing peers that

allowed_ips

list

false

-

tunnel_ips, tunnel_ip, tunneladdress, tunnel_adresses, tunnel_address, addresses, address, allowed

One or multiple IP addresses that are used inside the tunnel

public_key

string

false

-

pubkey, pub

Optionally provide an existing WireGuard Public Key. If none is provided - a key-pair will be generated automatically or the existing one will be used.

private_key

string

false

-

privkey, priv

Optionally provide an existing WireGuard Private Key. If none is provided - a key-pair will be generated automatically or the existing one will be used.

port

integer

false

-

-

Optionally provide a port for the server instance. Needed if dynamic peers will connect to this instance!

mtu

integer

false

1420

-

Integer between 1 and 9300

dns_servers

list

false

-

dns

List of DNS servers that will be used to resolve peer endpoint-names

disable_routes

boolean

false

false

disableroutes

If automatically created routes should be disabled. Needs to be set if you want to use policy-based routing, dynamic routing or ‘manually’ created static routes

gateway

string

false

-

gw

IP address to use as gateway. Can only be used if you enable the ‘disable_routes’ option.

vip

string

false

-

vip_depend, carp, carp_depend

The Virtual-CARP-IP (CARP VHID) to depend on. When this virtual address is not in master state, then the instance will be shutdown

reload

boolean

false

true

-

If the running config should be reloaded on change - this will take some time. For mass-managing items you might want to reload it ‘manually’ after all changes are done => using the reload module.

ansibleguy.opnsense.wireguard_peer

Parameter

Type

Required

Default value

Aliases

Comment

name

string

true

-

-

The unique name of the local WireGuard peer

endpoint

string

false

-

server_address, serveraddress, target, server

Peer endpoint IP address or DNS-hostname

allowed_ips

list

false for state changes, else true

-

tunnel_ips, tunnel_ip, tunneladdress, tunnel_adresses, tunnel_address, addresses, address, allowed

One or multiple IP addresses used by the peer inside the tunnel

public_key

string

false for state changes, else true

-

pubkey, pub

Provide the WireGuard Public Key of the peer. Used to identify the peer

psk

string

false

-

-

Optionally provide an PSK. The pre-shared key (PSK) is an optional security improvement as per the WireGuard protocol and should be a unique PSK per client for highest security.

port

integer

false

-

-

Optionally provide the port of the peer instance

keepalive

integer

false

-

-

Integer between 1 and 86400. Should be used if one of the connection-members is behind NAT

reload

boolean

false

true

-

If the running config should be reloaded on change - this will take some time. For mass-managing items you might want to reload it ‘manually’ after all changes are done => using the reload module.

ansibleguy.opnsense.wireguard_show

Parameter

Type

Required

Default value

Aliases

Comment

target

string

false

handshake

-

What information to query. One of: ‘handshake’, ‘config’

ansibleguy.opnsense.wireguard_general

Parameter

Type

Required

Default value

Aliases

Comment

enabled

boolean

false

true

-

Used to enable or disable the wireguard service

Usage

To make a dynamic WireGuard endpoint to re-connect you may want to create a gateway monitoring (dpinger) targeting the remote tunnel-address.

Examples

ansibleguy.opnsense.wireguard_general

- hosts: localhost
  gather_facts: no
  module_defaults:
    group/ansibleguy.opnsense.all:
      firewall: 'opnsense.template.ansibleguy.net'
      api_credential_file: '/home/guy/.secret/opn.key'

  tasks:
    - name: Example
      ansibleguy.opnsense.wireguard_general:
        # enabled: true

    - name: Enabling WireGuard service
      ansibleguy.opnsense.wireguard_general:
        enabled: true

ansibleguy.opnsense.wireguard_show

- hosts: localhost
  gather_facts: no
  module_defaults:
    group/ansibleguy.opnsense.all:
      firewall: 'opnsense.template.ansibleguy.net'
      api_credential_file: '/home/guy/.secret/opn.key'

  tasks:
    - name: Example
      ansibleguy.opnsense.wireguard_show:
        # target: 'handshake'

    - name: Querying the current WireGuard handshakes
      ansibleguy.opnsense.wireguard_show:
        target: 'handshake'
      register: wg_hands

    - name: Printing
      ansible.builtin.debug:
        var: wg_hands.data

ansibleguy.opnsense.wireguard_peer

- hosts: localhost
  gather_facts: no
  module_defaults:
    group/ansibleguy.opnsense.all:
      firewall: 'opnsense.template.ansibleguy.net'
      api_credential_file: '/home/guy/.secret/opn.key'

    ansibleguy.opnsense.list:
      target: 'wireguard_peer'

  tasks:
    - name: Example
      ansibleguy.opnsense.wireguard_peer:
        name: 'example'
        # allowed_ips: []
        # enpoint: ''
        # port: ''
        # public_key: ''
        # psk: ''
        # keepalive: ''
        # enabled: true
        # debug: false
        # state: 'present'
        # reload: true

    - name: Adding peer
      ansibleguy.opnsense.wireguard_peer:
        name: 'test1'
        endpoint: 'wg.template.ansibleguy.net'
        allowed_ips: ['10.200.0.1/32']
        public_key: 'gTuhGXA28/qRSLPnH3szr2+A4l3C4tKlUsOORV63+SE='

    - name: Disabling peer
      ansibleguy.opnsense.wireguard_peer:
        name: 'test1'
        enabled: false

    - name: Listing peers
      ansibleguy.opnsense.list:
      #  target: 'wireguard_peer'
      register: existing_entries

    - name: Printing
      ansible.builtin.debug:
        var: existing_entries.data

    - name: Removing peer
      ansibleguy.opnsense.wireguard_peer:
        name: 'test1'
        state: 'absent'

ansibleguy.opnsense.wireguard_server

- hosts: localhost
  gather_facts: no
  module_defaults:
    group/ansibleguy.opnsense.all:
      firewall: 'opnsense.template.ansibleguy.net'
      api_credential_file: '/home/guy/.secret/opn.key'

    ansibleguy.opnsense.list:
      target: 'wireguard_server'

  tasks:
    - name: Example
      ansibleguy.opnsense.wireguard_server:
        name: 'example'
        # allowed_ips: []
        # peers: []
        # port: ''
        # public_key: ''
        # private_key: ''
        # mtu: 1420
        # dns_servers: []
        # disable_routes: false
        # vip: ''
        # gateway: ''
        # enabled: true
        # debug: false
        # state: 'present'
        # reload: true

    - name: Adding server
      ansibleguy.opnsense.wireguard_server:
        name: 'test1'
        allowed_ips: ['10.200.0.1/32']
        peers: ['peer1']
        port: 51820
        vip: '192.168.2.1'

    - name: Disabling server
      ansibleguy.opnsense.wireguard_server:
        name: 'test1'
        enabled: false

    - name: Listing servers
      ansibleguy.opnsense.list:
      #  target: 'wireguard_server'
      register: existing_entries

    - name: Printing
      ansible.builtin.debug:
        var: existing_entries.data

    - name: Removing server
      ansibleguy.opnsense.wireguard_server:
        name: 'test1'
        state: 'absent'