Ansible 角色 - WireGuard 站点到站点 VPN

用于部署 WireGuard 站点到站点 VPN 设置的角色。

Molecule 日志: 简短, 完整

测试过的版本:

• Debian 11
• Raspbian 11
• Debian 12

安装

# 最新版
ansible-galaxy role install git+https://github.com/ansibleguy/infra_wireguard

# 从 Galaxy 安装
ansible-galaxy install ansibleguy.infra_wireguard

# 或者安装到自定义角色路径
ansible-galaxy install ansibleguy.infra_wireguard --roles-path ./roles

# 安装依赖
ansible-galaxy install -r requirements.yml
python3 -m pip install -r requirements.txt

---

贡献

欢迎你：

• 提交 PR

• 开始讨论

• 提交问题 => 在查看下面的故障排除指南后进行！

---

用法

想要一个简单的 Ansible GUI 吗？请查看我的 Ansible WebUI

示例

这里有一些详细的配置示例及其结果：

• 拓扑 - 单一
• 拓扑 - 星型
• 拓扑 - 网状

配置

你可以定义跨多个主机或主机组的 WireGuard 拓扑。

该角色将过滤出当前目标主机所属的拓扑并进行配置。

这些对等密钥必须与你的 Ansible 清单主机名匹配！

wireguard:
  restart_on_change: true  # 允许在更改时重启 wg 服务

  topologies:
    dc_nl:
      type: 'single'
      peers:
        srv02:
          Endpoint: 'srv02.wg.template.ansibleguy.net'
          Address: '10.100.0.1/30'

        srv03:
          Endpoint: 'srv03.wg.template.ansibleguy.net'
          Address: '10.100.0.2/30'

你可能会想使用 'ansible-vault' 来加密主机密钥文件：

ansible-vault encrypt roles/ansibleguy.infra_wireguard/files/keys/some_file.key

执行

运行 playbook：

ansible-playbook -K -D -i inventory/hosts.yml playbook.yml

或者如果你加密了密钥：

ansible-playbook -K -D -i inventory/hosts.yml playbook.yml --ask-vault-pass

还有一些有用的 标签 可用：

• base
• config
• tunnels
• purge

如果你只想 配置你的某个拓扑，可以在执行时设置以下变量：

ansible-playbook -K -D -i inventory/hosts.yml playbook.yml -e only_topo=TOPOLOGY_KEY

---

功能

• 软件包安装

  • WireGuard
  • Resolvconf (名称解析)

• 配置

  • 通过映射 拓扑 简化配置

  • 支持的拓扑：

    • 单一 - 简单连接两个节点
    • 星型 - 多个边缘/分支节点连接到一个中心集线器
    • 网状 - 连接每个对等节点到其他节点

  • 密钥

    • 为拓扑中的每个主机生成公钥/私钥对 (WG 使用公钥识别对等方)
    • 密钥写入控制器以保持一致性

  • 路由

    • 路由 由你管理！可以启用自动添加的 WG 路由或添加自定义的上/下脚本。

  • 默认配置：

    • 将私钥保存在文件中
    • 禁用路由自动添加 (防止锁定和自定义)
    • 启用系统日志记录和实例标识符
    • 在更改时重启 wg 服务

  • 默认选择：

    • 使用 PSK 增加安全性
    • 清理孤立的隧道

  • 默认不选：

    • 安装 'resolvconf' 以覆盖名称解析
    • 流量转发 (类似路由器)

  • 特点：

    • 如果服务重新启动失败，显示最后的日志
    • 动态对等节点的自动连接

---

信息

• 注意：此角色目前仅支持基于 Debian 的系统

• 注意：大多数角色功能可以选择启用或禁用。

  所有可用选项请参见 主默认文件 中的默认配置！

• 警告：并非所有设置/变量都会被检查有效性。配置错误可能会导致角色失效！

• 警告：请注意，WireGuard 上/下脚本是在 隧道服务 启动时执行的；而不是隧道连接。

  在规划/配置你的路由和度量时，可能需要考虑这一点！

• 信息：你应该保持拓扑名称简短。尽量避免使用特殊字符 => 它们会被自动移除 (除了 '_=+.-')，以确保密钥是有效的接口名！

• 信息：接口会被添加前缀：(可以按提供的方式更改)

  • 单一 => wgs_
  • 星型 => wgx_
  • 网状 => wgm_

• 信息：如何运行测试在 这里 进行了描述。

• 信息：主机密钥默认保存在角色的 'files' 目录中。

  这个密钥目录可以通过 'controller_key_store' 变量更改！

• 信息：如果你使用 OPNSense 防火墙，可以使用 ansibleguy.opnsense Ansible 收集 来管理这些 WireGuard 隧道。

---

故障排除

如果遇到连接问题，请按照以下步骤缩小故障源：

1. VPN 是否处于活动状态？

wg show all

如果没有：

• 连接无法建立 - 可能是配置错误或某些网络问题（_防火墙阻止流量_）

• 检查你的 WireGuard 日志：

# 'wgs_ts2' 是本示例中的 WireGuard 隧道接口
guy@srv:~# journalctl -u wg-quick@wgs_ts2
> -- 日志开始于 2022年2月8日 15:46:07 UTC，结束于 2022年2月8日 17:01:27 UTC。 --
> 2022年2月8日 16:12:31 test-ag-wg-s3 systemd[1]: 正在通过 wg-quick(8) 启动 WireGuard wgs_ts2...
> 2022年2月8日 16:12:31 test-ag-wg-s3 wireguard_wgs_ts2[10698]: [#] ip link add wgs_ts2 type wireguard
> 2022年2月8日 16:12:31 test-ag-wg-s3 wireguard_wgs_ts2[10698]: [#] wg setconf wgs_ts2 /dev/fd/63

• 这里是一些常见的错误信息，当你错误配置隧道时可能会看到：
  • 错误: RTNETLINK 反馈：地址已在使用中
    • 问题：每个隧道必须使用唯一端口进行监听 - 可能分配了重复的端口（或忘记将其设置为自定义）
  • 错误: 名称解析失败
    • 问题：服务尝试连接的 DNS 主机名没有正确设置，或你的目标主机在解析 DNS 时遇到问题
  • 错误：隧道配置完成，服务运行，但连接未建立
    • 问题：连接端口可能被防火墙阻止

2. 流量是否通过隧道？

ping 远程 WireGuard 隧道 IP - 在配置中这是 'Address'。

重要：请明确要使用的源 IP！

# .2 是远程 WG-IP； .1 是本地 IP
ping 10.0.1.2 -I 10.0.1.1

如果没有：

• 确保隧道真的在运行！
• 检查密钥是否匹配 => wg show all 应该在两侧显示 '相同的' 公钥：

guy@srv1:~# wg show all
> 接口: wgx_tx1
> 公钥: FJgEWygMdiqRcTvij3PiXOtPJNtTENQkv301l2PGhwY=
> ...

guy@srv2:~# wg show all
> ...
> 对等方: FJgEWygMdiqRcTvij3PiXOtPJNtTENQkv301l2PGhwY=
> ...

要重新生成不匹配的密钥，只需将其从控制器的 'files' 目录中删除，并在服务器上重新运行角色。

3. 流量是否经过隧道进行路由？

这 仅适用于 用于 连接远程子网 的隧道。

我们用另一个 ping 进行测试 - 这次使用本地子网（_不是 WG-IP_）。

# 172.30.1.1 是远程 '子网'； 172.20.0.1 是本地子网
ping 172.30.1.1 -I 172.20.0.1
# 你也可以运行 traceroute 获取更多关于路由的信息：
traceroute 172.30.1.1

如果你有动力，可以在远程主机上运行 tcpdump 看流量是否通过 '隧道'。

# 'wgs_ts2' 是本示例中的 WireGuard 隧道接口
guy@srv:~# tcpdump -i wgs_ts2
> tcpdump: 报文输出被压缩，使用 -v[v]... 获取完整协议解码
> 监听 wgs_ts2, 链接类型 RAW (Raw IP), 快照长度 262144 字节
> 17:00:07.336550 IP 10.0.1.2 > 10.0.1.1: ICMP echo 请求, id 38770, seq 1, length 64
> 17:00:07.336695 IP 10.0.1.1 > 10.0.1.2: ICMP echo 回复, id 38770, seq 1, length 64

如果没有：

• 检查防火墙是否阻止主机之间的任何流量。

  例如，IPTables/NFTables 需要允许传入和转发流量。

• 检查你的路由配置是否有错误，并与 '运行配置' 进行比较：

# 显示 '简单' 概览
ip route show all
# 显示所有路由
ip route show table all
# 去除不必要的广播/本地路由
ip route show table all | grep -vE '^(broadcast|local)\s'

• 主机需要支持流量转发！

  确保设置 'wireguard.support.traffic_forwarding' 被启用。

• 你可能忘记将目标网络添加到 'AllowedIPs' 中。

  这对于星型和网状拓扑是必要的！

4. 仍有问题

可能是角色问题/bug 或其他意外情况 => 请随时在 GitHub 上提交问题！

请在问题中提供故障排除的结果。