¶ imp1sh Ansible Collection für OpenWrt
Die deutsche Dokumentation wurde im Oktober 2022 durch die Englische ersetzt.
https://wiki.junicast.de/en/junicast/docs/AnsibleOpenWrtCollection
.
Diese Ansible Collection ist eine Sammlung von Rollen für OpenWrt. Das Ziel dieser Collection ist OpenWrt vollumfänglich über Ansible steuern zu können.
Die Collection befindet sich noch
in einem frühenim Entwicklungsstadium.Sie ist noch nicht zu 100% getestet.Sie ist mittlerweile ausreichend getestet um sie produktiv einsetzen zu können.
¶ Vorteile der imp1sh Ansible Collection
Die in dieser Collection integrierten Rollen sind sehr mächtig. In einigen Bereichen werden mehr Konfigurationsparameter abgebildet als in der LUCI Weboberfläche. Darüber hinaus ist man im Gegensatz zum LUCI in der Lage viele OpenWrt Instanzen zentral zu steuern. So kann man Konfigurationen selektiv auf einzelne Knoten ausrollen, auf selbst definierte Ansible Gruppen oder gar auf alle Geräte in einer Umgebung.
In dieser Hinsicht konkurriert es in gewisser Weise mit Lösungen wie OpenWisp. Es ist jedoch universeller, da das Standardwerkzeug Ansible Grundlage dieser Lösung ist.
Ideal ist diese Collection zum Beispiel für Umgebungen bei Providern oder Hostern, die ohne viel Aufwand viele Instanzen von Routern / Firewalls / Access Points verwalten möchten. Sie lohnt sich jedoch auch schon für kleinere Umgebungen mit wenigen Geräten, die man alle möglichst einheitlich konfiguriert haben möchte.
Des Weiteren kann man die großzügigen Vorteile von Ansible nutzen und Variablen einmal definieren und mehrfach nutzen. Dies vereinfacht die Verwaltung von großen Umgebungen fundamental. Selbst Platzhirsche wie pfSense lassen solche Features vermissen.
Gleichzeitig kann man auf die ganze Palette von Erweiterungsmöglichkeiten der hochflexiblen OpenWrt Lösung zurück greifen.
¶ Voraussetzungen OpenWrt Gerät
Diese Collection setzt python auf dem OpenWrt Gerät voraus, was in der Standardinstallation fehlt. Dies sind die Minimalanforderungen.
¶ Minimum
- 32 MB Storage
- Python3 auf dem OpenWrt Gerät
- OpenWrt Version 21.02 oder neuer
- 64+ MB, für Restic empfehle ich 512+ MB
¶ Empfehlung
Ja nach Anwendungsfall können die Anforderungen natürlich höher liegen, wenn zum Beispiel sehr viele Verbindungen verwaltet werden sollen. Je nachdem welche Zusatzpakete gewünscht sind, steigert das natürlich auch die Anforderungen an die Hardware. Generell empfehle ich jedoch folgende Werte:
- 128/256+ MB Storage
- 512+ MB RAM
¶ Installation
Wer noch kein Ansible einsetzt muss erst eine Grundkonfiguration anlegen, siehe Ansible Quickstart oder Ansible Getting Started.
Es wird ein System benötigt, dass als Ansible Controller fungiert um die Zielsysteme mit der Konfiguration zu versorgen. Der SSH public Key muss auf dem OpenWrt Zielsystem hinterlegt sein (System - Administration - SSH-Keys). Das Zielsystem muss per SSH erreichbar sein. Testweise von dem Ansible Controller verbinden auf das OpenWrt Gerät.
ssh root@<<ip oder hostname des openwrt systems>>
Der Login muss erfolgreich sein, ohne Fehlermeldungen und ohne Abfrage eines Passwortes.
Die Installation der Collection kann über den Befahl ansible-galaxy erfolgen, oder indem man das Github Repo pullt. Diese Anleitung geht von der Nutzung des Github Repos aus, da es aktueller ist als die in Galaxy gepflegte Version der Collection.
cd AnsibleArbeitsverzeichnis
ansible-galaxy collection install git+https://github.com/imp1sh/ansible_openwrt.git -p .collections
Alternativ kann die Collection auch in das Standardverzeichnis installiert werden via
cd AnsibleArbeitsverzeichnis
ansible-galaxy collection install git+https://github.com/imp1sh/ansible_openwrt.git
Die Ansible Collection geht davon aus, dass in der hosts.ini oder hosts.yml die Gruppe allhosts existiert, in der die zu verwaltenden OpenWrt Hosts enthalten sein müssen.
¶ Nutzung der Rollen
Die enthaltenen Rollen können in einem Playbook in solch einer Weise genutzt werden:
---
- hosts: manacdev
roles:
- imp1sh.ansible_openwrt.ansible_openwrtsystem
- imp1sh.ansible_openwrt.ansible_openwrtdropbear
- imp1sh.ansible_openwrt.ansible_openwrtservices
- imp1sh.ansible_openwrt.ansible_openwrtnetwork
- imp1sh.ansible_openwrt.ansible_openwrtfirewall
- imp1sh.ansible_openwrt.ansible_openwrtdhcp
¶ Konfiguration der Variablen
Diverse Variablen möchte man in Ansible entweder auf Host- oder auf Gruppenebene festlegen. Für gewissen Parameter wie z.B. die Firewallregeln oder -Zonen muss man unterschiedliche Variablen nutzen, je nachdem ob es auf Host- oder auf Gruppenebene festgesetzt werden soll.
Die Collection setzt für die Nutzung dieser speziellen Variablen mit Gruppenbezug das Vorhandensein der Gruppe allhosts voraus, innerhalb derer man dann die Variablen definiert.
Beispiel:
Man definiert für einen Host eine Firewallfreigabe in den vars des hosts selbst:
openwrt_firewall_ruleshost:
"icmp wan to dmz":
src: "WAN"
dest: "DMZ"
proto: "icmp"
target: "ACCEPT"
Möchte man jedoch z.B. Pakete auf bestimmten Gruppen bereitstellen, macht man dies in ./group_vars/allhosts.yml. Das Inventory muss natürlich so konfiguriert sein, dass die entsprechenden Hosts eben diesen Gruppen agehören.
openwrt_packagesinstallgroup:
openwrthosts:
- "acme"
- "acme-dnsapi"
- "coreutils"
- "flashrom"
- "htop"
- "luci-app-acme"
- "luci-app-statistics"
- "luci-app-vnstat2"
- "nmap-full"
- "python3"
- "screen"
- "tcpdump"
- "vim-fuller"
- "vnstat2"
- "vnstati2"
- "zabbix-agentd"
- "zabbix-extra-wifi"
openwrtaccesspoints:
- "ath10k-board-qca988x"
- "ath10k-firmware-qca988x"
- "ath9k-htc-firmware"
- "kmod-ath10k"
- "kmod-ath9k"
- "kmod-ath9k-common"
¶ Namenskonventionen Variablen
Variablennamen sind analog zu den Rollennamen gewählt. Der Wildcard (*) Teil ist immer der Teil aus uci. Für den Hostnamen gilt zum Beispiel:
openwrt_system_hostname
Rolle: imp1sh.ansible_openwrt.ansible_openwrtsystem
Variablen: openwrt_system_*
Rolle: imp1sh.ansible_openwrt.ansible_openwrtdropbear
Variablen: openwrt_dropbear_*
Rolle: imp1sh.ansible_openwrt.ansible_openwrtservices
Variablen: openwrt_services_*
Rolle: imp1sh.ansible_openwrt.ansible_openwrtnetwork
Variablen: openwrt_network_*
Rolle: imp1sh.ansible_openwrt.ansible_openwrtfirewall
Variablen: openwrt_firewall_*
Rolle: imp1sh.ansible_openwrt.ansible_openwrtdhcp
Variablen: openwrt_dhcp_*
Rolle: imp1sh.ansible_openwrt.ansible_openwrtpackages
Variablen: òpenwrt_packages_*
Rolle: imp1sh.ansible_openwrt.ansible_openwrtrestic
Variablen: openwrt_restic_*
Rolle: imp1sh.ansible_openwrt.ansible_openwrtdhcp
Variablen: openwrt_dhcp_*
¶ Rollen der OpenWrt Collection
Die Aufgaben sind klar in die verschiedenen Rollen eingeteilt. Sie können einzeln benutzt werden, wenn man nur bestimme Dinge über Ansible kontrollieren möchte. Es bietet sich jedoch an das komplette System mit den Rollen aus der Collection zu verwalten. Sollte ein Feature fehlen oder ein Fehler gefunden werden einfach ein Ticket auf github öffnen.
imp1sh.ansible_openwrt.ansible_openwrtacme- imp1sh.ansible_openwrt.ansible_openwrtbabeld
- imp1sh.ansible_openwrt.ansible_openwrtbatmanadv
- imp1sh.ansible_openwrt.ansible_openwrtbmx7
- imp1sh.ansible_openwrt.ansible_openwrtdhcp
- imp1sh.ansible_openwrt.ansible_openwrtdropbear
- imp1sh.ansible_openwrt.ansible_openwrtfirewall
- imp1sh.ansible_openwrt.ansible_openwrtnetwork
- imp1sh.ansible_openwrt.ansible_openwrpackages
- imp1sh.ansible_openwrt.ansible_openwrtrestic
- imp1sh.ansible_openwrt.ansible_openwrtservices
- imp1sh.ansible_openwrt.ansible_openwrtsqm
- imp1sh.ansible_openwrt.ansible_openwrtsystem
- imp1sh.ansible_openwrt.ansible_openwrtwireless
- imp1sh.ansible_openwrt.ansible_openwrtwireguard