Skip to content

Latest commit

 

History

History
414 lines (254 loc) · 11.9 KB

REFERENCE.md

File metadata and controls

414 lines (254 loc) · 11.9 KB
Raw

Reference

Table of Contents

Classes

Defined types

Public Defined types

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

Classes

wireguard

manages the wireguard package

Parameters

The following parameters are available in the wireguard class:

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: {}

Defined types

wireguard::interface

}

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'},],
}

Parameters

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

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 ferm rule will be created

Default value: 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'))

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[1280, 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: []

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: []

Data types

Wireguard::Peers

custom data type for an array with wireguard peers

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]],
  }]]