REFERENCE.md

Reference

Table of Contents

Classes

• wireguard: manages the wireguard package

Defined types

Public Defined types

• wireguard::interface: manages a wireguard setup

Private Defined types

• wireguard::provider::systemd: Manage the systemd components of a wireguard setup
• wireguard::provider::wgquick: Manage the wg quick components of a wireguard setup

Data types

• Wireguard::Peers: custom data type for an array with wireguard peers

Classes

wireguard

manages the wireguard package

Parameters

The following parameters are available in the wireguard class:

• manage_package
• package_name
• package_ensure
• config_directory
• purge_unknown_keys
• interfaces
• default_allowlist

manage_package

Data type: Boolean

if the package should be managed or not

Default value: true

package_name

Data type: String[1]

the name of the package

Default value: 'wireguard-tools'

package_ensure

Data type: Enum['installed', 'latest', 'absent']

the ensure state of the package

Default value: 'installed'

config_directory

Data type: Stdlib::Absolutepath

the path to the wireguard directory

Default value: '/etc/wireguard'

purge_unknown_keys

Data type: Boolean

by default Puppet will purge unknown wireguard keys from $config_directory

Default value: true

interfaces

Data type: Hash[String[1], Any]

hash of interfaces to create. Provides hiera integration.

Default value: {}

default_allowlist

Data type: Array[Stdlib::IP::Address]

array of allowed IP ranges for interfaces. Can be overwritten for individual interfaces

Default value: ['fe80::/64', 'fd00::/8', '0.0.0.0/0']

Defined types

wireguard::interface

}

• See also
  • https://www.freedesktop.org/software/systemd/man/systemd.netdev.html#%5BWireGuardPeer%5D%20Section%20Options

Examples

Peer with one node and setup dualstack firewall rules

wireguard::interface {'as2273':
  source_addresses => ['2003:4f8:c17:4cf::1', '149.9.255.4'],
  public_key       => 'BcxLll1BVxGQ5DeijroesjroiesjrjvX+EBhS4vcDn0R0=',
  endpoint         => 'wg.example.com:53668',
  addresses        => [{'Address' => '192.168.123.6/30',},{'Address' => 'fe80::beef:1/64'},],
}

Peer with one node and setup dualstack firewall rules with peers in a different layer2

wireguard::interface {'as2273':
  source_addresses => ['2003:4f8:c17:4cf::1', '149.9.255.4'],
  public_key       => 'BcxLll1BVxGQ5DeijroesjroiesjrjvX+EBhS4vcDn0R0=',
  endpoint         => 'wg.example.com:53668',
  addresses        => [{'Address' => '192.168.218.87/32', 'Peer' => '172.20.53.97/32'}, {'Address' => 'fe80::ade1/64',},],
}

Create a passive wireguard interface that listens for incoming connections. Useful when the other side has a dynamic IP / is behind NAT

wireguard::interface {'as2273':
  source_addresses => ['2003:4f8:c17:4cf::1', '149.9.255.4'],
  public_key       => 'BcxLll1BVxGQ5DeijroesjroiesjrjvX+EBhS4vcDn0R0=',
  dport            => 53668,
  addresses        => [{'Address' => '192.168.218.87/32', 'Peer' => '172.20.53.97/32'}, {'Address' => 'fe80::ade1/64',},],
}

create a wireguard interface behind a DSL line with changing IP with lowered MTU

wireguard::interface {'as3668-2':
  source_addresses      => ['144.76.249.220', '2a01:4f8:171:1152::12'],
  public_key            => 'Tci/bHoPCjTpYv8bw17xQ7P4OdqzGpEN+NDueNjUvBA=',
  endpoint              => 'router02.bastelfreak.org:1338',
  dport                 => 1338,
  input_interface       => $facts['networking']['primary'],
  addresses             => [{'Address' => '169.254.0.10/32', 'Peer' =>'169.254.0.9/32'},{'Address' => 'fe80::beef:f/64'},],
  destination_addresses => [],
  persistent_keepalive  => 5,
  mtu                   => 1412,

create a wireguard interface with multiple peers where one uses a preshared key

wireguard::interface { 'wg0':
  dport     => 1338,
  addresses => [{'Address' => '192.0.2.1/24'}],
  peers     => [
    {
       public_key  => 'foo==',
       preshared_key => '/22q9I+RpWRsU+zshW8skv1p00TvnEE6fTvPJuI2Cp4=',
       allowed_ips => ['192.0.2.2'],
    },
    {
       public_key  => 'bar==',
       allowed_ips => ['192.0.2.3'],
    }
  ],
}

create two sides of a session using the public key from the other side

wireguard::interface { 'wg0':
  source_addresses => ['2003:4f8:c17:4cf::1', '149.9.255.4'],
  public_key       => $facts['wireguard_pubkeys']['nodeB'],
  endpoint         => 'nodeB.example.com:53668',
  addresses        => [{'Address' => '192.168.123.6/30',},{'Address' => 'fe80::beef:1/64'},],
}

Peer with one node, setup dualstack firewall rules and RoutingPolicyRule

wireguard::interface {'as2273':
  source_addresses        => ['2003:4f8:c17:4cf::1', '149.9.255.4'],
  public_key              => 'BcxLll1BVxGQ5DeijroesjroiesjrjvX+EBhS4vcDn0R0=',
  endpoint                => 'wg.example.com:53668',
  addresses               => [{'Address' => '192.168.123.6/30',},{'Address' => 'fe80::beef:1/64'},],
  extra_networkd_sections => {
    'RoutingPolicyRule' => [
      {
        'From'              => '10.0.0.0/24',
        'Table'             => '1010',
        'IncomingInterface' => 'as2273',
      },
    ],
  },
}

Parameters

The following parameters are available in the wireguard::interface defined type:

• interface
• ensure
• input_interface
• manage_firewall
• dport
• table
• firewall_mark
• source_addresses
• destination_addresses
• public_key
• endpoint
• addresses
• persistent_keepalive
• description
• mtu
• peers
• routes
• extra_networkd_sections
• private_key
• preshared_key
• provider
• preup_cmds
• postup_cmds
• predown_cmds
• postdown_cmds
• endpoint_port

interface

Data type: String[1]

the title of the defined resource, will be used for the wg interface

Default value: $title

ensure

Data type: Enum['present', 'absent']

will ensure that the files for the provider will be present or absent

Default value: 'present'

input_interface

Data type: String[1]

ethernet interface where the wireguard packages will enter the system, used for firewall rules

Default value: $facts['networking']['primary']

manage_firewall

Data type: Boolean

if true, a nftables rule will be created

Default value: $facts['os']['family'] ? { 'Gentoo' => false, default => true

dport

Data type: Integer[1024, 65000]

destination for firewall rules / where our wg instance will listen on. defaults to the last digits from the title

Default value: Integer(regsubst($title, '^\D+(\d+)$', '\1'))

table

Data type: Optional[String[1]]

Routing table to add routes to

Default value: undef

firewall_mark

Data type: Optional[Integer[0, 4294967295]]

netfilter firewall mark to set on outgoing packages from this wireguard interface

Default value: undef

source_addresses

Data type: Array[Stdlib::IP::Address]

an array of ip addresses from where we receive wireguard connections

Default value: []

destination_addresses

Data type: Array[Stdlib::IP::Address]

array of addresses where the remote peer connects to (our local ips), used for firewalling

Default value: delete_undef_values([$facts['networking']['ip'], $facts['networking']['ip6'],])

public_key

Data type: Optional[String[1]]

base64 encoded pubkey from the remote peer

Default value: undef

endpoint

Data type: Optional[String[1]]

fqdn:port or ip:port where we connect to

Default value: undef

addresses

Data type: Array[Hash[String,Variant[Stdlib::IP::Address::V4,Stdlib::IP::Address::V6]]]

different addresses for the systemd-networkd configuration

Default value: []

persistent_keepalive

Data type: Integer[0, 65535]

is set to 1 or greater, that's the interval in seconds wireguard sends a keepalive to the other peer(s). Useful if the sender is behind a NAT gateway or has a dynamic ip address

Default value: 0

description

Data type: Optional[String[1]]

an optional string that will be added to the wireguard network interface

Default value: undef

mtu

Data type: Optional[Integer[1200, 9000]]

configure the MTU (maximum transision unit) for the wireguard tunnel. By default linux will figure this out. You might need to lower it if you're connection through a DSL line. MTU needs to be equal on both tunnel endpoints

Default value: undef

peers

Data type: Wireguard::Peers

is an array of struct (Wireguard::Peers) for multiple peers

Default value: []

routes

Data type: Array[Hash[String[1], Variant[String[1], Boolean]]]

different routes for the systemd-networkd configuration

Default value: []

extra_networkd_sections

Data type: Hash[String, Array[Hash[String, Any]]]

additional sections for the systemd-networkd configuration

Default value: {}

private_key

Data type: Optional[String[1]]

Define private key which should be used for this interface, if not provided a private key will be generated

Default value: undef

preshared_key

Data type: Optional[String[1]]

Define preshared key for the remote peer

Default value: undef

provider

Data type: Enum['systemd', 'wgquick']

The specific backend to use for this wireguard::interface resource

Default value: 'systemd'

preup_cmds

Data type: Array[String[1]]

is an array of commands which should run as preup command (only supported by wgquick)

Default value: []

postup_cmds

Data type: Array[String[1]]

is an array of commands which should run as preup command (only supported by wgquick)

Default value: []

predown_cmds

Data type: Array[String[1]]

is an array of commands which should run as preup command (only supported by wgquick)

Default value: []

postdown_cmds

Data type: Array[String[1]]

is an array of commands which should run as preup command (only supported by wgquick)

Default value: []

endpoint_port

Data type: Optional[Stdlib::Port]

optional outgoing port from the other endpoint. Will be used for firewalling. If not set, we will try to parse $endpoint

Default value: undef

Data types

Wireguard::Peers

custom data type for an array with wireguard peers

• See also
  • https://www.freedesktop.org/software/systemd/man/systemd.netdev.html#%5BWireGuardPeer%5D%20Section%20Options

Alias of

Array[Struct[{
    public_key           => String[1],
    preshared_key        => Optional[String[1]],
    allowed_ips          => Optional[Array[String[1]]],
    endpoint             => Optional[String[1]],
    persistent_keepalive => Optional[Stdlib::Port],
    description          => Optional[String[1]],
  }]]