Rol de Ansible - VPN Site-to-Site de WireGuard

Rol para implementar configuraciones de VPN Site-to-Site de WireGuard.

Registros de Molecule: Corto, Completo

Probado en:

• Debian 11
• Raspbian 11
• Debian 12

Instalación

# última versión
ansible-galaxy role install git+https://github.com/ansibleguy/infra_wireguard

# desde Galaxy
ansible-galaxy install ansibleguy.infra_wireguard

# o para una ruta de rol personalizada
ansible-galaxy install ansibleguy.infra_wireguard --roles-path ./roles

# instalar dependencias
ansible-galaxy install -r requirements.yml
python3 -m pip install -r requirements.txt

---

Contribuciones

Siéntete libre de:

• Abrir solicitudes de extracción (PR)

• Iniciar discusiones

• Abrir problemas => ¡después de revisar la guía de solución de problemas a continuación!

---

Uso

¿Quieres una interfaz gráfica simple para Ansible? Consulta mi Ansible WebUI

Ejemplos

Aquí hay algunos ejemplos detallados de configuración y sus resultados:

• Topología - Única
• Topología - Estrella
• Topología - Malla

Configuración

Puedes definir tus topologías de WireGuard que abarcan múltiples hosts o grupos de hosts.

El rol filtrará las topologías a las que el host de destino actual pertenece y configurará esas.

¡Las claves de los pares deben coincidir con los nombres de los hosts en tu inventario de Ansible!

wireguard:
  restart_on_change: true  # permitir que los servicios de wg se reinicien ante cambios

  topologías:
    dc_nl:
      tipo: 'única'
      pares:
        srv02:
          Endpoint: 'srv02.wg.template.ansibleguy.net'
          Dirección: '10.100.0.1/30'

        srv03:
          Endpoint: 'srv03.wg.template.ansibleguy.net'
          Dirección: '10.100.0.2/30'

Puede que desees usar 'ansible-vault' para cifrar los archivos de clave del host:

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

Ejecución

Ejecuta el playbook:

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

O si has cifrado tus claves:

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

También hay algunas etiquetas útiles disponibles:

• base
• config
• tunnels
• purge

Si solo deseas provisionar una de tus topologías, puedes establecer la siguiente variable en el momento de la ejecución:

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

---

Funcionalidad

• Instalación de paquetes

  • WireGuard
  • Resolvconf (resolución de nombres)

• Configuración

  • Configuración simplificada por medio del mapeo de topologías

  • Topologías soportadas:

    • única - conecta simplemente dos nodos
    • estrella - múltiples nodos extremos/conexión a un hub central
    • malla - conecta cada uno de los pares a cada otro

  • Claves

    • Generación de pares de claves públicas/privadas para cada host en una topología (WG identifica al par por clave pública)
    • Las claves se escriben en el controlador para consistencia

  • Enrutamiento

    • ¡El enrutamiento es tu responsabilidad! Podrías habilitar las rutas WG agregadas automáticamente o agregar scripts personalizados para subir/bajar.

  • Configuración por defecto:

    • Guardar la clave privada en un archivo
    • Deshabilitar la adición automática de rutas (anti-bloqueo y personalización)
    • Habilitar el registro de syslog con identificadores de instancia
    • Reiniciar el servicio wg ante cambios

  • Opciones por defecto habilitadas:

    • Usar PSK para seguridad adicional
    • Eliminación de túneles huérfanos

  • Opciones por defecto deshabilitadas:

    • Instalación de 'resolvconf' para anulación de resolución de nombres
    • Reenvío de tráfico (como un enrutador)

  • Características:

    • Mostrar los últimos registros si el servicio falla al reiniciarse
    • Conexión automática de pares dinámicos

---

Información

• Nota: este rol actualmente solo soporta sistemas basados en Debian

• Nota: La mayoría de la funcionalidad del rol puede ser habilitada o deshabilitada.

  Para todas las opciones disponibles, consulta la configuración predeterminada ubicada en el archivo principal de predeterminados!

• Advertencia: No se verificará la validez de cada configuración/variable que proporciones. Una mala configuración podría romper el rol.

• Advertencia: Ten en cuenta que los scripts de subida/bajada de WireGuard se ejecutan cuando el SERVICIO DEL TÚNEL se activa; NO LA CONEXIÓN DEL TÚNEL.

  Esto puede ser importante al planificar/configurar tus rutas y métricas.

• Información: Deberías mantener los nombres de tus topologías cortos. Y evitar usar caracteres especiales => se eliminarán automáticamente (excepto '_=+.-') para que la clave sea un nombre de interfaz válido.

• Información: Las interfaces tendrán un prefijo prepended: (se puede cambiar según se proporcione)

  • única => wgs_
  • estrella => wgx_
  • malla => wgm_

• Información: Cómo ejecutar pruebas está descrito aquí.

• Información: Las claves de host se guardarán en el directorio de 'files' del rol de forma predeterminada.

  Este directorio de claves se puede cambiar usando la variable 'controller_key_store'.

• Información: Si estás usando firewalls OPNSense - puedes usar la colección Ansible ansibleguy.opnsense para gestionar esos túneles de WireGuard.

---

Solución de Problemas

Si encuentras problemas de conectividad => sigue estos pasos para reducir su origen:

1. ¿Está activo el vpn?

wg show all

Si no:

• No se puede establecer la conexión - puede haber un error de configuración o un problema de red (firewall bloqueando el tráfico)

• Revisa tus registros de WireGuard:

  # 'wgs_ts2' es la interfaz del túnel WireGuard en este ejemplo
  guy@srv:~# journalctl -u wg-quick@wgs_ts2
  > -- El registro comienza el mar 08 de feb 2022 15:46:07 UTC, termina el mar 08 de feb 2022 17:01:27 UTC. --
  > Feb 08 16:12:31 test-ag-wg-s3 systemd[1]: Iniciando WireGuard a través de wg-quick(8) para wgs_ts2...
  > Feb 08 16:12:31 test-ag-wg-s3 wireguard_wgs_ts2[10698]: [#] ip link add wgs_ts2 type wireguard
  > Feb 08 16:12:31 test-ag-wg-s3 wireguard_wgs_ts2[10698]: [#] wg setconf wgs_ts2 /dev/fd/63
  

  • Aquí hay algunos mensajes de error comunes que puedes ver al configurar mal tus túneles:
    • Error: RTNETLINK answers: Address already in use
      • Problema: cada túnel debe usar un puerto único para escuchar; puede que hayas asignado un puerto duplicado (o te olvidaste de configurarlo en uno personalizado)
    • Error: failure in name resolution
      • Problema: el nombre de host DNS al que el servicio intenta conectarse no está configurado (correctamente) o tu host de destino tiene problemas generales para resolver DNS
    • Error: Se han configurado túneles, los servicios están funcionando, pero la conexión no está activa
      • Problema: el puerto de conexión podría estar bloqueado por un firewall

2. ¿Está el tráfico pasando por el túnel?

Haz ping a la IP remota del túnel de WireGuard - en la configuración, esta es la 'Dirección'.

Importante: ¡define la IP de origen a usar!

# .2 es la IP remota de WG; .1 es la local
ping 10.0.1.2 -I 10.0.1.1

Si no:

• Asegúrate de que el túnel realmente esté funcionando.

• Verifica si las claves coinciden => wg show all debería mostrar 'las mismas' claves públicas en ambos lados:

  guy@srv1:~# wg show all
  > interface: wgx_tx1
  > public key: FJgEWygMdiqRcTvij3PiXOtPJNtTENQkv301l2PGhwY=
  > ...
  

  guy@srv2:~# wg show all
  > ...
  > peer: FJgEWygMdiqRcTvij3PiXOtPJNtTENQkv301l2PGhwY=
  > ...
  

  Para regenerar claves que no coincidan, simplemente elimínalas del directorio de 'files' del controlador y vuelve a ejecutar el rol en los servidores.

3. ¿Está el tráfico siendo enrutado a través del túnel?

Esto solo aplica a túneles que se usan para conectar subredes remotas.

Lo probamos con otro ping - esta vez usando la subred local (no la IP de WG).

# 172.30.1.1 es la 'subred' remota; 172.20.0.1 es la local
ping 172.30.1.1 -I 172.20.0.1
# también puedes ejecutar un traceroute para obtener más información sobre la ruta tomada:
traceroute 172.30.1.1

Si estás motivado => puedes ejecutar un tcpdump en el host remoto para descubrir si el tráfico está pasando 'a través del túnel'.

# 'wgs_ts2' es la interfaz del túnel WireGuard en este ejemplo
guy@srv:~# tcpdump -i wgs_ts2
> tcpdump: salida detallada suprimida, usa -v[v]... para una codificación de protocolo completa
> escuchando en wgs_ts2, tipo de enlace RAW (Raw IP), longitud de instantánea 262144 bytes
> 17:00:07.336550 IP 10.0.1.2 > 10.0.1.1: ICMP echo request, id 38770, seq 1, length 64
> 17:00:07.336695 IP 10.0.1.1 > 10.0.1.2: ICMP echo reply, id 38770, seq 1, length 64

Si no:

• Verifica si un firewall está bloqueando el tráfico entre los hosts.

  IPTables/NFTables necesitan permitir tanto el tráfico entrante COMO el reenvío.

• Revisa tu configuración de enrutamiento en busca de errores y compárala contra la 'configuración activa':

  # muestra un resumen 'simple'
  ip route show all
  # muestra TODAS las rutas
  ip route show table all
  # para eliminar rutas innecesarias de difusión/local
  ip route show table all | grep -vE '^(broadcast|local)\s'
  

• ¡Los hosts deben soportar el reenvío de tráfico!

  Asegúrate de que la configuración 'wireguard.support.traffic_forwarding' esté habilitada.

• Podrías haberte olvidado de agregar la red de destino a 'AllowedIPs'.

  Esto es necesario para las topologías de estrella y malla.

4. ¿Sigues teniendo problemas?

Puede ser un problema de rol/error o algún otro caso específico => ¡no dudes en abrir un problema en GitHub!

Proporciona los resultados de la solución de problemas en el problema.