WireGuard Role¶

Overview¶

WireGuard is a modern, high-performance VPN protocol built into the Linux kernel. The solti-ensemble WireGuard role automates client configuration for secure remote connectivity, primarily for connecting to existing WireGuard servers. Its purpose is to provide secure remote access to monitoring infrastructure, encrypted data transport for metrics and logs, and NAT traversal.

Requirements¶

Ansible 2.9+
Target system with a Linux kernel supporting WireGuard (e.g., Debian 12, Rocky Linux 9, Ubuntu 24).

Installation / Quick Start¶

Basic Client Configuration¶

- hosts: remote_hosts
  become: true
  roles:
    - role: jackaltx.solti_ensemble.wireguard
      vars:
        wireguard_state: present
        wireguard_endpoint: "hub.example.com:51820"
        wireguard_server_public_key: "{{ vault_wg_server_pubkey }}" # Store in Ansible Vault
        wireguard_client_address: "10.10.0.20/24"
        wireguard_allowed_ips: "10.10.0.0/24"

Client with Pre-Shared Key¶

- hosts: remote_hosts
  become: true
  roles:
    - role: jackaltx.solti_ensemble.wireguard
      vars:
        wireguard_endpoint: "hub.example.com:51820"
        wireguard_server_public_key: "{{ vault_wg_server_pubkey }}"
        wireguard_preshared_key: "{{ vault_wg_psk }}" # Store in Ansible Vault
        wireguard_client_address: "10.10.0.20/24"
        wireguard_allowed_ips: "10.10.0.0/24"

Role Variables / Configuration¶

Required Variables¶

Name	Description
`wireguard_endpoint`	The public endpoint (IP or hostname and port) of the WireGuard server.
`wireguard_server_public_key`	The public key of the WireGuard server (store in Ansible Vault).
`wireguard_client_address`	The IP address/CIDR to assign to the client within the VPN tunnel.

Optional Variables¶

Name	Description	Default
`wireguard_state`	`present` to install, `absent` to remove.	`present`
`wireguard_allowed_ips`	A comma-separated list of IP addresses or CIDR blocks to route through the VPN. Use `0.0.0.0/0` to route all traffic.	`10.10.0.0/24`
`wireguard_dns`	DNS server IP address(es) to use inside the VPN.	`""`
`wireguard_persistent_keepalive`	Interval in seconds to send keepalive packets. Used for NAT traversal. Set to `0` to disable.	`25`
`wireguard_preshared_key`	An optional pre-shared key for additional encryption (store in Ansible Vault).	`""`
`wireguard_interface`	The name of the WireGuard interface.	`wg0`
`wireguard_backup_enabled`	Enable automated backup of generated keys and configuration.	`true`
`wireguard_backup_dir`	Directory for backups.	`/root/wireguard-backup`

Usage¶

View Connection Status¶

wg show

Check Connectivity¶

# Ping VPN gateway
ping -c 3 10.10.0.11

# Test monitoring endpoint (example)
curl -I http://10.10.0.11:8086/health

Service Management¶

# Check status
systemctl status wg-quick@wg0

# Start/Stop/Restart
systemctl start wg-quick@wg0
systemctl stop wg-quick@wg0
systemctl restart wg-quick@wg0

Troubleshooting¶

Connection Not Establishing¶

Check service status and logs: systemctl status wg-quick@wg0 and journalctl -u wg-quick@wg0 -f.
Verify configuration file: cat /etc/wireguard/wg0.conf.
Check key consistency: client public key must be added to server's configuration, and server public key must match client's wireguard_server_public_key.
Test endpoint reachability: nc -vzu hub.example.com 51820.

No Handshake¶

Firewall blocking UDP port 51820.
Incorrect endpoint address or key mismatch.
Server not running.
Enable debug logging: echo module wireguard +p > /sys/kernel/debug/dynamic_debug/control then journalctl -kf | grep wireguard.

Can Ping VPN but Not Services¶

Check routing: ip route show (should show route via wg0).
Check services listening on the VPN interface (e.g., ss -tulpn | grep 10.10.0.11).

Role-Specific Sections¶

Key Management¶

The role automatically generates client private/public key pairs and securely stores them. Public keys can be retrieved from /etc/wireguard/publickey or via wg show wg0 public-key. Keys are backed up to a configurable location.

Network Configuration¶

AllowedIPs Patterns: Configure which IP addresses or networks are routed through the VPN tunnel.
Persistent Keepalive: Essential for maintaining connections through NAT/firewalls.

Firewall Configuration¶

Client and server firewalls must allow UDP traffic on the WireGuard port (default 51820).

Integration with solti-monitoring¶

This role is crucial for securely integrating remote hosts with the solti-monitoring stack by establishing a VPN tunnel for metrics and logs.

Removal¶

The role supports both removing the service while keeping configuration (wireguard_remove_config: false) or a complete removal including configuration and backups (wireguard_remove_config: true).