Wireguard
Modern state-of-the-art VPN designed to be simplier and faster that IPsec and openVPN.
Ansible Role: wireguard
Only the server endpoint needs to be exposed publically. Clients can globally roam as long as they have working Internet connections and can send UDP traffic to the given port.
Role handles all steps that are provided in this documentation.
# Wireguard
Wireguard installation with wireguard-initramfs support.
## Requirements
No additional requirements.
## Role Variables
Settings have been throughly documented for usage.
[defaults/main.yml](https://github.com/r-pufky/ansible_wireguard/blob/main/defaults/main/main.yml).
[defaults/adapter.yml](https://github.com/r-pufky/ansible_wireguard/blob/main/defaults/main/adapter.yml).
[defaults/initramfs.yml](https://github.com/r-pufky/ansible_wireguard/blob/main/defaults/main/initramfs.yml).
### Ports
All ports and protocols have been defined for the role.
Hosts should only define firewall rules for ports they need.
[defaults/ports.yml](https://github.com/r-pufky/ansible_wireguard/blob/main/defaults/main/ports.yml).
## Dependencies
N/A
## Example Playbook
Store wireguard vault material in group_vars for client/server access.
### With wireguard-initramfs
host_vars/client.example.com/vars/wireguard.yml
``` yaml
wireguard_initramfs_enable: true
wireguard_boot_interface: 'client'
wireguard_boot_interface_address: '172.31.255.11/32'
wireguard_boot_peer_public_key: '{{ vault_wireguard_server_public_key }}'
wireguard_boot_peer_endpoint: 'wireguard-server.example.com:51820'
wireguard_boot_client_private_key: '{{ vault_wireguard_client_boot_private_key }}'
wireguard_boot_persistent_keepalives: '25'
wireguard_boot_allowed_ips: '172.31.255.254/32'
wireguard_adapter_config:
- {adapter: 'client',
interface: {
Address: '172.31.255.10/32',
SaveConfig: 'False',
PrivateKey: '{{ vault_wireguard_client_private_key }}',
},
peers: [
{
PublicKey: '{{ vault_wireguard_server_public_key }}',
AllowedIPs: '172.31.255.254/32,172.31.255.5/32',
EndPoint: 'wireguard-server.example.com:51820',
PersistentKeepalive: 25
},
]
}
```
### Without wireguard-initramfs
host_vars/client.example.com/vars/wireguard.yml
``` yaml
wireguard_initramfs_enable: true
wireguard_adapter_config:
- {adapter: 'tunnel',
interface: {
Address: '172.31.255.10/32',
SaveConfig: 'False',
PrivateKey: '{{ vault_wireguard_client_private_key }}',
},
peers: [
{
PublicKey: '{{ vault_wireguard_server_public_key }}',
AllowedIPs: '172.31.255.254/32,172.31.255.5/32',
EndPoint: 'wireguard-server.example.com:51820',
PersistentKeepalive: 25
},
]
}
```
host_vars/wireguard-server.example.com/vars/wireguard.yml
``` yaml
wireguard_adapter_config:
- {adapter: 'tunnel',
interface: {
Address: '172.31.255.5/32',
SaveConfig: 'False',
PrivateKey: '{{ vault_wireguard_server_private_key }}',
},
peers: [
{
PublicKey: '{{ vault_wireguard_client_public_key }}',
AllowedIPs: '172.31.255.254/32,172.31.255.10/32',
EndPoint: '10.9.9.251:51820',
PersistentKeepalive: 25
},
]
}
```
site.yml
``` yaml
- name: 'wireguard server'
hosts: 'wireguard-server.example.com'
become: true
roles:
- 'r_pufky.wireguard'
- name: 'wireguard client'
hosts: 'client.example.com'
become: true
roles:
- 'r_pufky.wireguard'
```
## Issues
Create a bug and provide as much information as possible.
Associate pull requests with a submitted bug.
## License
[AGPL-3.0 License](https://github.com/r-pufky/ansible_wireguard/blob/main/LICENSE)
## Author Information
https://keybase.io/rpufky
None
Role Details: Updated: 2022-10-08 galaxy source service docs Reference
Ports
---
###############################################################################
# Ports Configuration
###############################################################################
# Ports should be managed externally via an OS role.
#
# Port exposure is only required for wireguard servers accepting connetions.
#
# Reference:
# * https://docs.ansible.com/ansible/latest/collections/community/general/ufw_module.html
ports:
- {proto: 'udp', from_ip: 'any', to_port: 51820, direction: 'in', comment: 'wireguard service'}
Defaults
---
###############################################################################
# Wireguard Role Configuration
###############################################################################
#
# Reference:
# * https://wireguard.com
# * https://github.com/pirate/wireguard-docs
# Enable wireguard-initramfs. This will allow the use of wireguard during the
# kernel init process (dropbear over wireguard support).
#
# Reference: initramfs.yml
wireguard_initramfs_enable: false
# Enable IP forwarding for wireguard clients. This will enable clients to talk
# to each other if their wireguard configurations allow them to do so.
wireguard_ipv4_forwarding: false
wireguard_ipv6_forwarding: false
# Force refresh adapters. This will remove all existing adapters before
# creating them. If you are connecting to the host over wireguard, this can
# potentially BREAK YOUR CONNECTION. Useful for renaming or removing adapters.
wireguard_force_refresh_adapters: false
InitRAMFS
---
###############################################################################
# Wireguard-initramfs (wireguard kernel init support) Configuration
###############################################################################
# Wireguard keys and network should be different from the wireguard network
# used on boot, as /boot is generally unencrypted and should be considered
# compromised/untrusted.
#
# Generate keys using wireguard/files/scripts/wggen {HOST}. Store
# vault-encrypted keys in group_vars so both client and server can be
# configured without duplication.
#
# Reference:
# * https://github.com/r-pufky/wireguard-initramfs
# Wireguard interface name.
wireguard_boot_interface: 'example_vpn'
# CIDR wireguard interface address.
wireguard_boot_interface_address: '172.31.255.10/32'
# Peer public key (server's public key). Use vault.
wireguard_boot_peer_public_key: ''
# IP:PORT of the peer (server); any reachable IP/DNS.
wireguard_boot_peer_endpoint: 'wg.example.com:51820'
# Client Private key (client private key). Use vault.
wireguard_boot_client_private_key: ''
# Keepalives. Required to ensure connection for non-exposed ports.
wireguard_boot_persistent_keepalives: '25'
# CIDR IP's allowed on wireguard connection, typically the peer (server).
wireguard_boot_allowed_ips: '172.31.255.254/32'
Adapters
---
###############################################################################
# Wireguard Adapter Configuration
###############################################################################
# List of dicts containing wireguard adapters to setup. ALL configuration
# options can be specified dynamically as needed.
#
# Generate keys using wireguard/files/scripts/wggen {HOST}. Store
# vault-encrypted keys in group_vars so both client and server can be
# configured without duplication.
#
# Reference:
# * https://manpages.debian.org/unstable/wireguard-tools/wg.8.en.html
#
# wireguard_adapter_config:
# - {adapter: {ADAPTER NAME},
# interface: {Address: {IP/CIDR}, PrivateKey: {VAULT CLIENT PRIVATE}, SaveConfig: 'False'},
# peers: [
# {PublicKey: {VAULT SERVER PUBLIC}, EndPoint: { server ip/dns:port }, AllowedIPs: {IP/CIDR}},
# ]
# }
#
# Server:
# wireguard_adapter_config:
# - {adapter: 'tunnel',
# interface: {
# Address: '172.31.255.254/24',
# SaveConfig: 'False',
# ListenPort: 51820,
# PrivateKey: '{{ vault_wireguard_server_private_key }}',
# },
# peers: [
# {PublicKey: '{{ vault_wireguard_client_public_key }}', AllowedIPs: '172.31.255.10/32'},
# ]
# }
#
# Client:
# wireguard_adapter_config:
# - {adapter: 'tunnel',
# interface: {
# Address: '172.31.255.10/24',
# SaveConfig: 'False',
# PrivateKey: '{{ vault_wireguard_client_private_key }}',
# },
# peers: [
# {
# PublicKey: '{{ vault_wireguard_server_public_key }}',
# AllowedIPs: '172.31.255.254/32',
# EndPoint: 'wireguard-server.example.com:51820',
# PersistentKeepalive: 25
# },
# ]
# }
wireguard_adapter_config: []