Rôle Ansible : openwrt

Gérez OpenWRT et ses dérivés avec Ansible, mais sans Python.

En plaçant un hôte dans le groupe d'inventaire openwrt, certains modules sont remplacés par une version shell fonctionnant sur une installation standard d'OpenWRT, en essayant de préserver la plupart des fonctionnalités d'origine. Les hôtes qui ne sont pas dans ce groupe ne sont pas affectés. Cela permet de mélanger des tâches avec OpenWRT et d'autres plateformes. Il y a également quelques nouveaux modules spécifiques à OpenWRT inclus (comme uci). Toutes les combinaisons d'arguments ne sont pas testées ! Certains cas ont seulement été traduits de Python par souci de complétude.

Actuellement, les modules suivants sont implémentés :

• command
• copy
• fetch (implicite)
• file
• lineinfile
• nohup (nouveau)
• opkg
• ping
• service
• setup
• shell (implicite)
• slurp
• stat
• sysctl
• template (implicite)
• uci (nouveau)
• wait_for_connection (implicite)

Pour réaliser tout cela, quelques modifications sont nécessaires (au cas où vous vous poseriez des questions sur les vars_plugins).

Compatibilité

Ce rôle a été testé avec succès avec :

• LEDE 17.01 (manuellement)
• OpenWRT 18.06
• OpenWRT 19.07
• OpenWRT 21.02
• OpenWRT 22.03

Exigences

Certains modules nécessitent éventuellement un moyen de générer des hachages SHA1 ou d'encoder des données en Base64. Dans le cas de la Base64, il y a une implémentation très lente avec hexdump | awk. Pour SHA1, il n'y a pas de solution de contournement. Les modules essaieront de trouver des commandes système utilisables pour SHA1 (sha1sum, openssl) et pour Base64 (base64, openssl, solution de contournement) lorsque nécessaire. Si aucune commande utilisable n'est trouvée, la plupart des fonctions fonctionneront toujours, mais le module fetch, par exemple, devra être exécuté avec validate_checksum: no, téléchargera toujours le fichier et retournera changed: yes. Il est donc recommandé d'installer coreutils-sha1sum et coreutils-base64, si les commandes ne sont pas déjà fournies par busybox. Le rôle le fait automatiquement par défaut (voir ci-dessous).

Variables du rôle

openwrt_install_recommended_packages:
    Vérifie la présence de certaines commandes et installe les paquets correspondants s'ils sont
    manquants. Voir les exigences ci-dessus. (par défaut : oui)

openwrt_scp_if_ssh:
    Indique s'il faut utiliser scp au lieu de sftp pour les systèmes OpenWRT. La valeur peut être `yes`,
    `no` ou `smart`. Ansible par défaut utilise `smart`, mais ce rôle par défaut utilise `yes`
    car OpenWRT n'offre pas sftp par défaut. (par défaut : oui)

openwrt_remote_tmp:
    Paramètre remote_tmp d'Ansible pour les systèmes OpenWRT. Par défaut, il est réglé sur /tmp pour éviter
    l'usure du flash sur l'appareil cible. (par défaut : /tmp)

openwrt_wait_for_connection, openwrt_wait_for_connection_timeout:
    Indique s'il faut attendre l'hôte (par défaut : oui) et combien de temps (300) après un
    redémarrage réseau ou wifi (voir les gestionnaires).

openwrt_ssh, openwrt_scp, openwrt_ssh_host, openwrt_ssh_user, openwrt_user_host:
    Raccourcis d'aide pour faire des choses comme
    "command: {{ openwrt_scp }} {{ openwrt_user_host|quote }}:/etc/rc.local /tmp"

Exemple de Playbook

Inventaire :

[aps]
ap1.example.com
ap2.example.com
ap3.example.com

[routers]
router1.example.com

[openwrt:children]
aps
routers

Playbook :

- hosts: openwrt
  roles:
    - gekmihesg.openwrt
  tasks:
    - name: copier l'image openwrt
      command: "{{ openwrt_scp }} image.bin {{ openwrt_user_host|quote }}:/tmp/sysupgrade.bin"
      delegate_to: localhost
    - name: démarrer sysupgrade
      nohup:
        command: sysupgrade -q /tmp/sysupgrade.bin
    - name: attendre le redémarrage
      wait_for_connection:
        timeout: 300
        delay: 60
    - name: installer mdns
      opkg:
        name: mdns
        state: present
    - name: activer et démarrer mdns
      service:
        name: mdns
        state: started
        enabled: yes
    - name: copier les clés autorisées
      copy:
        src: authorized_keys
        dest: /etc/dropbear/authorized_keys
    - name: revenir sur les changements en attente
      uci:
        command: revert
    - name: configurer l'interface wifi radio0
      uci:
        command: set
        key: wireless.radio0
        value:
          phy: phy0
          type: mac80211
          hwmode: 11g
          channel: auto
    - name: configurer l'interface wifi
      uci:
        command: section
        config: wireless
        type: wifi-iface
        find_by:
          device: radio0
          mode: ap
        value:
          ssid: MySSID
          encryption: psk2+ccmp
          key: très secret
    - name: valider les changements
      uci:
        command: commit
      notify: recharger le wifi

Il est également possible d'exécuter les modules en dehors d'un playbook comme ceci :

$ export ANSIBLE_LIBRARY=~/.ansible/roles/gekmihesg.openwrt/library
$ export ANSIBLE_VARS_PLUGINS=~/.ansible/roles/gekmihesg.openwrt/vars_plugins
$ ansible -i openwrt-hosts -m setup all

Licence

Licence Publique Générale GNU v3.0 (voir https://www.gnu.org/licenses/gpl-3.0.txt)

Développement

Écrire des modules personnalisés pour ce cadre n'est pas très difficile. Les modules sont enveloppés dans un script wrapper, qui fournit quelques fonctions communes pour l’analyse des paramètres, le traitement JSON, la génération de réponses, et d'autres. Tous les modules doivent correspondre au format openwrt_<nom_du_module>.sh. Si nom_du_module n'est pas l'un des modules principaux d'Ansible, il doit également y avoir un <nom_du_module>.py. Ce dernier n’a pas besoin d’avoir fonctionnel (il peut avoir des fonctions pour les systèmes non OpenWRT) et peut contenir la documentation.

Assurez-vous d'installer les paquets de requirements.txt dans votre environnement virtuel et, avec le venv activé, exécutez :

$ molecule test

avant de valider et de soumettre votre PR.

Il est également fortement recommandé d'écrire des tests pour votre nouveau module.