OpenWrt-Admin: správa domácí OpenWrt sítě z Home Assistantu

Doma mám několik přístupových bodů s OpenWrt, router s OpenWrt a spravovaný switch – a dlouho jsem pro ně neměl jedno místo, kde bych viděl, co se v síti děje. Tak jsem si napsal add-on do Home Assistantu: OpenWrt-Admin. Běží na Raspberry Pi 4 vedle Home Assistantu a všechno spravuje přes SSH a SNMP, na zařízeních nic neinstaluje.

Proč vlastní add-on

LuCI je skvělé, ale na každém AP zvlášť – a přepínat mezi záložkami s IP adresami mě nebavilo. Chtěl jsem jednu stránku, kde uvidím všechny AP, klienty na Wi-Fi i kabelu, a kde jedním tlačítkem změním SSID nebo restartuju zařízení.

Hotová řešení byla buď moc velká (celý controller), nebo jen na čtení. Home Assistant už doma běží nonstop, má přihlašování uživatelů a umí add-ony – tak proč ho nevyužít.

A přiznám se: add-on jsem nepsal sám, ale spolu s Claudem od Anthropicu. Já jsem říkal, co chci, posílal výstupy z AP a switche a všechno zkoušel na své síti; Claude psal kód, překlady i návod. Každou verzi jsem si pak sám commitnul do Gitey a nasadil v Home Assistantu.

Co add-on umí

Během pár večerů vzniklo přes deset verzí a z „prohlížeče AP“ je dnes docela plná správa domácí sítě:

  • Přehled – karta pro každé AP, router i switch: online/offline, uptime, firmware, zatížení, počet klientů, čekající aktualizace.
  • Klienti – všechny Wi-Fi klienty ze všech AP v jedné tabulce (SSID, pásmo, signál, rychlost, doba připojení). Jména se berou z registru zařízení Home Assistantu, z DHCP a z rezervací na routeru, takže místo MAC adres vidím „Teploměr-sklep“.
  • SSID – změna názvu, hesla, skrytí a vypnutí sítě najednou na všech AP, s náhledem změn před uložením.
  • Akce – restart zařízení, apk update / upgrade, odpojení klienta z Wi-Fi nebo jeho blokace na 10 minut až 24 hodin (na všech AP se stejným SSID).
  • Mapa sítě – router, switch, AP, SSID a klienti se spojnicemi podle VLAN (víc níže).
  • Porty – stav a vyjednaná rychlost každého portu (1 Gb/s, 100 Mb/s, half-duplex) a co je do něj zapojené.
  • Upozornění na nové zařízení – když se v síti objeví MAC, kterou add-on ještě neviděl, přijde notifikace do Home Assistantu (a volit. do mobilu).
  • Zálohy konfigurace – sysupgrade -b každého zařízení jednou za týden; zálohy leží v datech add-onu, takže jsou i v zálohách Home Assistantu.
  • Uživatelé a práva – podle uživatelů Home Assistantu: někdo má plný přístup, někdo jen čtení.
  • Čeština a angličtina – rozhraní i návod, jazyk se bere z Home Assistantu.
Image description

Přehled – všechna zařízení na jedné stránce (demo režim, vymyšlená data).

Image description

Klienti ze všech AP najednou, jména z Home Assistantu a nabídka pro odpojení nebo blokaci.

Mapa sítě

Nejvíc mě baví mapa. Add-on ji kreslí sám z toho, co na zařízeních najde – nic se ručně nezakresluje. U mě doma vypadá takhle: internet → router → switch Netgear GS724T → tři AP (půda, sklep, UniFi), servery a další zařízení na portech switche.

  • VLANy – add-on pozná VLANy z názvů zařízení (eth0.30, br-lan.10), členů bridge a uci. Každá síť má barvu (LAN, IoT, host, DMZ…) a na spojnicích jsou štítky tagovaných VLAN.
  • Wi-Fi klienti visí pod svým SSID přerušovanou čarou, se signálem.
  • Kabelová zařízení – tady to bylo zajímavé. Moje AP mají vestavěný switch a některá zařízení jsou zapojená přímo do nich. Add-on čte tabulku MAC adres switche v AP (swconfig dev switch0 get arl_table) a pozná, které zařízení je na kterém portu. Port s MAC adresou routeru je uplink, zbytek jsou lokální porty.
  • Spravovaný switch – GS724T se čte přes SNMP (jen čtení). Na mapě je jako samostatný uzel, AP do něj zapojená mají každé vlastní čáru s rychlostí portu.
  • Rychlosti – u každé čáry je 1G zeleně nebo 100M oranžově. Díky tomu jsem hned našel AP, které je ke switchi připojené jen stovkou – nejspíš kabel.
  • Zoom a posun myší, když je zařízení hodně.

Když je zařízení vidět z více míst (MAC notebooku zapojeného do AP vidí i switch), patří tomu nejhlubšímu – tedy AP, ne switchi. Stejně add-on pozná, že je AP zapojené za jiným AP nebo za switchem.

Image description

Mapa sítě – router → switch → AP, Wi-Fi klienti pod SSID, kabelová zařízení na portech s rychlostí.

Image description

Porty switche přes SNMP – oranžově porty jen na 100 Mb/s.

Jak to funguje uvnitř

Add-on je malá aplikace v Pythonu (FastAPI, Jinja2, HTMX), která se otevírá přímo v postranním panelu Home Assistantu. Na AP a router se přihlašuje přes SSH vlastním klíčem a čte to, co OpenWrt už samo nabízí – žádný agent ani balíček na zařízeních není potřeba.

CoOdkud
Wi-Fi klienti, SSID, signálubus call hostapd.<if> get_clients, network.wireless status
rozhraní, VLANy, IPubus call network.interface dump, network.device status, uci show network
DHCP klienti a rezervace/tmp/dhcp.leases, uci show dhcp na routeru
kabelová zařízení na portech APswconfig dev switch0 get arl_table, /proc/net/arp
rychlost portůswconfig dev switch0 show, network.device status
změna SSIDuci set wireless.… && uci commit wireless && wifi reload
odpojení / blokace klientaubus call hostapd.<if> del_client s ban_time
aktualizace a zálohyapk update, apk list --upgradable, sysupgrade -b
switchSNMP v2c: IF-MIB, BRIDGE-MIB, Q-BRIDGE-MIB
jména zařízení, notifikacewebsocket API Home Assistantu

SNMP klient je napsaný přímo v add-onu (asi 200 řádků, GETBULK přes UDP), takže nepřibývá žádná další knihovna. Používá jen standardní MIB, takže by měl fungovat se skoro každým spravovaným switchem – Netgear, TP-Link, Cisco SG, Zyxel.

Instalace v Home Assistantu

Repozitář mám na vlastní Gitei a zrcadlím ho na GitHub. Home Assistant si add-on stáhne sám a nabídne aktualizaci, když pushnu novou verzi.

  1. V Home Assistantu: Nastavení → Doplňky → Obchod s doplňky → ⋮ → Repozitáře a přidat URL repozitáře. Repozitář mimo GitHub (např. vlastní Gitea) jde přidat i v terminálu: ha store add <URL>.
  2. Nainstalovat OpenWrt-Admin a spustit. Při prvním startu si vytvoří SSH klíč a na stránce Nastavení ho ukáže.
  3. Veřejnou část klíče přidat na každé AP a router do /etc/dropbear/authorized_keys.
  4. V konfiguraci add-onu vyplnit zařízení:
aps:
  - name: Router
    host: 192.168.1.1
    type: router
  - name: AP-Obyvak
    host: 192.168.1.2
  - name: AP-Kancelar
    host: 192.168.1.3
switches:                 # volitelně, SNMP jen pro čtení
  - name: Switch
    host: 192.168.1.5
    community: public
full_access: [radim]      # uživatelé HA s plným přístupem
read_access: [host]       # jen čtení

U switche je potřeba zapnout SNMP v2c s read-only community a povolit adresu Home Assistantu. Na Netgearu GS724T je to v System → SNMP → Community Configuration – a pozor, nový záznam se ukládá tlačítkem Add, ne Apply.

Na co jsem cestou narazil

  • Switch zapomíná. Tabulka MAC adres ve switchi drží záznam jen pár minut od posledního rámce. Tiché zařízení (u mě IP telefon Cisco) tak co chvíli „utíkalo“ z AP k routeru. Řešení: add-on si pamatuje poslední známý port a router tichá zařízení jednou za 4 minuty pingne, aby se switch znovu učil.
  • ARP podle IP, ne podle MAC. Router má stejnou MAC v LAN i ve VLAN, takže tabulka klíčovaná podle MAC přepisovala záznamy a uplink se nenašel.
  • Čip má víc portů než krabice. UniFi AP LR ukazoval pět portů vestavěného switche, přitom zásuvka vede rovnou na eth0. A na jiném AP se objevil „port 6, 10 Mb/s half-duplex“ – druhý CPU port čipu AR8327. Teď se ukazují jen porty použité v konfiguraci VLAN switche.
  • WAN není klient. V ARP routeru je i brána poskytovatele; záznamy z WAN a tunelů (WireGuard) se musí odfiltrovat.
  • Náhodné MAC telefonů. Telefony používají pro každou Wi-Fi soukromou MAC, takže upozornění na nová zařízení je umí označit nebo vynechat.
  • Blokace klienta žije jen v paměti. hostapd ji zapomene při restartu Wi-Fi – a blokovat se musí na všech AP se stejným SSID, jinak se klient připojí jinde.

Co dál

Aktuální verze je 0.14.2 a doma běží denně. V plánu mám nastavení rádií (kanál, šířka pásma, výkon) s přehledem AP na stejném kanálu, historii klientů a jejich roamingu mezi AP a možná i log z AP přímo na stránce.

Add-on je psaný tak, aby ho mohl použít kdokoli s OpenWrt: žádné moje zařízení v kódu, ukázkový demo režim, návod česky i anglicky. Kdo to zkusí, dejte vědět, jak to běží na vašich krabičkách.