ansible-wireguard-openwisp

Rôle Ansible qui installe WireGuard et des scripts de gestion pour OpenWISP. Une fois installé et configuré correctement avec OpenWISP, les pairs WireGuard sont gérés automatiquement par OpenWISP sans besoin d'intervention manuelle.

Ce rôle peut également configurer des scripts pour permettre à OpenWISP de gérer les tunnels VXLAN sur WireGuard.

Testé sur Debian et Ubuntu.

REMARQUE : il est fortement conseillé d'utiliser cette procédure sur des machines virtuelles propres ou des conteneurs Linux.

Version minimale d'ansible supportée : 2.10.

Instructions d'installation et d'utilisation

Pour plus de simplicité, le plus facile est d'installer ce rôle sur votre machine locale via ansible-galaxy :

ansible-galaxy install openwisp.wireguard_openwisp

Consultez l'exemple de playbook dans la section "Exemple complet de playbook avec certificat SSL" de cette documentation pour commencer rapidement avec ce rôle.

REMARQUE : Ce rôle ne configurera pas le transfert de paquets ni n'ajoutera de routes statiques ou dynamiques sur votre serveur.

Étant donné que la manière exacte dont les paquets peuvent être routés peut varier selon différents facteurs et besoins qui peuvent différer grandement d'une organisation à l'autre, il est laissé à l'utilisateur de le configurer selon ses besoins. Nous pourrions ajouter une configuration par défaut de routage/transfert à l'avenir une fois que nous aurons plus de données d'utilisation, si cela vous intéresse, veuillez nous le faire savoir.

Exemple complet de playbook avec certificat SSL

Par défaut, le playbook crée un certificat SSL auto-signé (non approuvé) pour le point de terminaison VPN. Si vous gardez le certificat non approuvé, vous devrez également désactiver la vérification SSL sur OpenWISP, bien que nous déconseillons d'utiliser ce type de configuration en environnement de production. Vous pouvez installer votre propre certificat de confiance en suivant les étapes de cette section.

La première chose à faire est de configurer un domaine valide pour votre VPN WireGuard, cela signifie que votre fichier d'inventaire (hôtes) doit ressembler à ceci :

[openwisp2_wireguard]
wireguard.votredomaine.com

Vous devez être en mesure d'ajouter un enregistrement DNS pour wireguard.votredomaine.com, vous ne pouvez pas utiliser une adresse IP à la place de wireguard.votredomaine.com.

Une fois votre domaine configuré et l'enregistrement DNS propagé, procédez à l'installation du rôle ansible geerlingguy.certbot

ansible-galaxy install geerlingguy.certbot

Ensuite, créez votre playbook.yml de manière à ce qu'il ressemble à l'exemple suivant :

- hosts: openwisp2_wireguard
  become: "{{ become | default('yes') }}"
  roles:
    - geerlingguy.certbot
    - openwisp.wireguard_openwisp
  vars:
    openwisp2_wireguard_controller_url: "https://openwisp.votredomaine.com"
    openwisp2_wireguard_vpn_uuid: "collez-uuid-vpn-ici"
    openwisp2_wireguard_vpn_key: "collez-vpn-key-ici"
    openwisp2_wireguard_flask_key: "collez-token-auth-point-de-terminaison"

    # Certificats SSL
    openwisp2_wireguard_ssl_cert: "/etc/letsencrypt/live/{{ ansible_fqdn }}/fullchain.pem"
    openwisp2_wireguard_ssl_key: "/etc/letsencrypt/live/{{ ansible_fqdn }}/privkey.pem"

    # Configuration de certbot
    certbot_auto_renew_user: "utilisateur-privilégié-pour-renouveler-les-certificats"
    certbot_auto_renew_minute: "20"
    certbot_auto_renew_hour: "5"
    certbot_create_if_missing: true
    certbot_create_standalone_stop_services: []
    certbot_certs:
      - email: "collez-votre-email"
        domains:
          - wireguard.votredomaine.com

Lisez la documentation de geerlingguy.certbot pour en savoir plus sur la configuration du rôle certbot.

Pour connaître toutes les variables ansible fournies par openwisp.wireguard_openwisp, lisez la section "Variables de rôle" de cette documentation.

Configuration de plusieurs interfaces WireGuard

En utilisant ce rôle, vous pouvez configurer plusieurs interfaces WireGuard sur la même machine gérées indépendamment par OpenWISP. Vous devrez vous assurer que les variables de rôle suivantes sont uniques pour chaque playbook :

• openwisp2_wireguard_path
• openwisp2_wireguard_flask_port

Voici un exemple de playbook contenant deux plays pour configurer plusieurs interfaces WireGuard.

- name: Configurer la première interface WireGuard
  hosts:
    - wireguard
  become: "{{ become | default('yes') }}"
  roles:
    - openwisp.wireguard_openwisp
  vars:
    openwisp2_wireguard_controller_url: "https://openwisp.votredomaine.com"
    openwisp2_wireguard_path: "/opt/wireguard-openwisp/wireguard-1"
    openwisp2_wireguard_vpn_uuid: "collez-vpn1-uuid-ici"
    openwisp2_wireguard_vpn_key: "collez-vpn1-key-ici"
    openwisp2_wireguard_flask_key: "collez-vpn1-token-auth-point-de-terminaison"
    openwisp2_wireguard_flask_port: 8081

- name: Configurer la seconde interface WireGuard
  hosts:
    - wireguard
  become: "{{ become | default('yes') }}"
  roles:
    - openwisp.wireguard_openwisp
  vars:
    openwisp2_wireguard_controller_url: "https://openwisp.votredomaine.com"
    openwisp2_wireguard_path: "/opt/wireguard-openwisp/wireguard-2"
    openwisp2_wireguard_vpn_uuid: "collez-vpn-2-uuid-ici"
    openwisp2_wireguard_vpn_key: "collez-vpn-2-key-ici"
    openwisp2_wireguard_flask_key: "collez-vpn-2-token-auth-point-de-terminaison"
    openwisp2_wireguard_flask_port: 8082

Points à considérer

• Lors de la création d'objets de serveur VPN dans OpenWISP, assurez-vous que le nom de l'interface et le port sont uniques pour chaque VPN. Sinon, les scripts de mise à jour ne fonctionneront pas correctement en raison de conflits.

Variables de rôle

Ce rôle dispose de nombreuses valeurs de variables qui peuvent être modifiées pour s'adapter au mieux à vos besoins.

Voici toutes les variables que vous pouvez personnaliser (vous voudrez peut-être également jeter un œil aux valeurs par défaut de ces variables).

- hosts: openwisp2_wireguard
  become: "{{ become | default('yes') }}"
  roles:
    - openwisp.wireguard_openwisp
  vars:
    # URL de l'instance OpenWISP, vous pouvez omettre cela (supprimez-le) si WireGuard
    # est installé sur le même hôte que celui sur lequel OpenWISP fonctionne.
    # Si vous utilisez deux hôtes séparés (un pour OpenWISP et un pour WireGuard),
    # ce qui est une bonne idée, vous devrez spécifier l'URL de votre
    # instance OpenWISP (exécutant OpenWISP Controller >= 1.0.0) ici
    openwisp2_wireguard_controller_url: "https://openwisp.votredomaine.com"
    # Répertoire où installer les scripts de mise à jour
    openwisp2_wireguard_path: "/opt/wireguard-openwisp"
    # Permet de télécharger la configuration VPN en utilisant des connexions SSL "non sécurisées".
    # Il est recommandé de laisser cela à false.
    openwisp2_wireguard_curl_insecure: false
    # UUID du VPN généré après avoir créé un objet de serveur VPN dans OpenWISP
    openwisp2_wireguard_vpn_uuid: "collez-vpn-uuid-ici"
    # Clé du VPN généré après avoir créé un objet de serveur VPN dans OpenWISP
    openwisp2_wireguard_vpn_key: "collez-vpn-key-ici"
    # Point de terminaison Flask à utiliser pour déclencher les mises à jour
    openwisp2_wireguard_flask_endpoint: "/trigger-update"
    # Clé d'autorisation du point de mise à jour
    openwisp2_wireguard_flask_key: "collez-token-auth-point-de-terminaison"
    # Port où le point de terminaison Flask est exécuté
    openwisp2_wireguard_flask_port: 8081
    # Hôte où le point de terminaison Flask est exécuté
    openwisp2_wireguard_flask_host: 0.0.0.0
    # Définit le niveau de journalisation pour la journalisation Flask.
    # Les valeurs autorisées sont "INFO", "WARNING" et "ERROR"
    openwisp2_wireguard_logging_level: "WARNING"
    # Commande utilisée pour exécuter uwsgi depuis le superviseur
    openwisp2_wireguard_uwsgi_command: "{{ openwisp2_wireguard_path }}/env/bin/uwsgi uwsgi.ini"

    # spécifiez le chemin vers un certificat SSL valide et une clé
    # (un certificat SSL auto-signé sera généré si omis)
    openwisp2_wireguard_ssl_cert: "/opt/wireguard-openwisp/ssl/server.crt"
    openwisp2_wireguard_ssl_key: "/opt/wireguard-openwisp/ssl/server.key"
    # personnalisez les informations sur le certificat SSL auto-signé si nécessaire
    openwisp2_wireguard_ssl_country: "FR"
    openwisp2_wireguard_ssl_state: "Île-de-France"
    openwisp2_wireguard_ssl_locality: "Paris"
    openwisp2_wireguard_ssl_organization: "Département IT"

    # par défaut python3 est utilisé, cela peut nécessiter de le régler sur python2.7 pour les systèmes plus anciens
    openwisp2_wireguard_python: python2.7
    # commande virtualenv pour votre distribution distante, généralement réglée automatiquement
    openwisp2_wireguard_virtualenv_command: "virtualenv"

    # Définit la méthode ipv4 du VXLAN, par défaut à "link-local"
    openwisp2_wireguard_vxlan_ipv4_method: disabled
    openwisp2_wireguard_vxlan_ipv6_method: disabled

Dépannage

Voici comment déclencher manuellement la vérification de configuration si nécessaire :

sudo -u openwisp /opt/wireguard-openwisp/update_wireguard.sh check_config

Les journaux de l'application responsable de la mise à jour de la configuration WireGuard téléchargée depuis le serveur OpenWISP se trouvent dans /opt/wireguard-openwisp/vpn_updater.log.

Contribuer

Veuillez lire les directives de contribution d'OpenWISP.

Comment exécuter des tests

Si vous souhaitez contribuer à ansible-wireguard-openwisp, vous devez exécuter des tests dans votre environnement de développement pour vous assurer que vos modifications ne cassent rien.

Pour ce faire, procédez comme suit :

Étape 1 : Clonez ansible-wireguard-openwisp

Clonez le dépôt avec :

git clone https://github.com/<votre_fork>/ansible-wireguard-openwisp.git

Étape 2 : Installez Docker

Si vous n'avez pas encore installé Docker, vous devez l'installer (exemple pour les systèmes Linux Debian/Ubuntu) :

sudo apt-get install docker.io

Étape 3 : Installez Molecule et ses dépendances

pip install molecule[docker,ansible] yamllint ansible-lint docker

Étape 4 : Téléchargez les images Docker

docker pull geerlingguy/docker-ubuntu2204-ansible:latest
docker pull geerlingguy/docker-ubuntu2004-ansible:latest
docker pull geerlingguy/docker-debian11-ansible:latest

Étape 5 : Exécutez le test Molecule

molecule test -s local

Si vous ne recevez aucun message d'erreur, cela signifie que les tests ont été exécutés avec succès.

Astuce : Utilisez molecule test -s local --destroy=never pour accélérer les exécutions de tests ultérieures.

License

Voir LICENSE.

Support

Voir Canaux de support OpenWISP.