klant toevoegen (WireGuard + HA-backup)

De klant bouwt zelf de tunnel op naar OPNsense. Gepetto haalt de nieuwste HA-backup over die tunnel op en zet hem op de PBS. Elke klant krijgt een eigen peer, tunnel-IP, keypair en script.

 

Vaste gegevens

Deze waarden zijn voor elke klant dezelfde. Alleen de peer-naam en het tunnel-IP verschillen.

Onderdeel	Waarde
Hub	OPNsense (Zeus), WireGuard-instance haoniriaxyz (wg0)
Endpoint voor klanten	lan.oniria.xyz:51820 (UDP)
WAN-regel	WANTelenetCoax, UDP, destination This Firewall, poort 51820
Tunnel-subnet	10.99.0.0/24, de hub is 10.99.0.1
Allowed IPs op de klant	10.99.0.0/24
Keepalive	25 seconden
Naamschema peer	<klantcode>oniriaxyz, bv. eroniriaxyz
Add-on bij de klant	WireGuard Client (bigmoby), repository https://github.com/bigmoby/hassio-repository-addon
Backup-host	Gepetto: scripts in /diy, backupmappen in /backupHosts/<klant>
PBS	winniedepoeh.oniria.be, datastore Backups_USB, backup-id per klant

Bijhouden bij elke nieuwe klant:

Klant	Peer	Tunnel-IP	Opmerking
VE (lab)	veoniriaxyz	10.99.0.2	Labmachine, controleer dat hij een eigen keypair heeft
ER	eroniriaxyz	10.99.0.3	Tunnel werkt, ping vanaf Gepetto werkt

Stap 1: voorbereiding

Kies vooraf twee dingen en noteer ze in de tabel hierboven.

1. Klantcode van twee letters, bv. er. De peer heet dan eroniriaxyz.
2. Een vrij tunnel-IP 10.99.0.x/32. Kijk in OPNsense onder VPN → WireGuard → Peers welke IP's al bestaan. Het IP hoort bij de klant, niet bij de volgorde van aanmaken.
3. Controleer dat het klantnetwerk niet in 10.99.0.x zit. Zo wel, dan botst de route.
4. Weet vooraf of de klant een SSH-add-on heeft of kan krijgen (nodig voor de backup in stap 6).

Stap 2: peer aanmaken in OPNsense

De Peer generator maakt het keypair en de config voor de klant. De private key van de klant zie je alleen op dit moment.

1. OPNsense → VPN → WireGuard → Peer generator.
2. Vul in:

• Instance: haoniriaxyz
• Name: <klantcode>oniriaxyz
• Address: 10.99.0.x/32
• Endpoint: lan.oniria.xyz:51820
• Allowed IPs: 10.99.0.0/24
• Keepalive interval: 25
• DNS Servers: leeg
• Store private key on this firewall: uit

Klik op het tandwiel bij Public key voor een nieuw keypair. Scroll naar onder en klik Store and generate next. Kopieer de config uit het tekstvak (vanaf [Interface]). Deel hem niet via screenshot, chat of mail. VPN → WireGuard → Instances → potlood bij haoniriaxyz → bij Peers de nieuwe peer aanvinken → Save → Apply. VPN → WireGuard → Peers: open de nieuwe peer en controleer dat Endpoint address en Endpoint port leeg zijn. De klant belt naar jou, niet omgekeerd. Staat daar een endpoint, dan stuurt OPNsense zijn pakketten naar zichzelf.

Elk toestel krijgt een eigen keypair. Hergebruik nooit een key voor twee toestellen: dan negeert OPNsense een van de twee zonder foutmelding.

Stap 3: WireGuard Client op de HA van de klant

Gebruik niet de officiële WireGuard-add-on: die is alleen een server en kan geen verbinding maken met OPNsense.

1. Instellingen → Add-ons → Add-on store → menu ⋮ rechtsboven → Repositories.
2. Voeg toe: https://github.com/bigmoby/hassio-repository-addon, sluit en herlaad de pagina.
3. Installeer WireGuard Client.
4. Open Configuratie en vul in met de waarden uit de config van stap 2:

• Adres van de interface: 10.99.0.x/32
• Private key: PrivateKey uit [Interface]
• Peer, public key: PublicKey uit [Peer]
• Peer, endpoint: lan.oniria.xyz:51820 (altijd invullen, zonder endpoint faalt de verbinding stil)
• Peer, allowed IPs: 10.99.0.0/24
• Keepalive: 25

Opslaan, de add-on starten en het Logboek openen.

Let op bij allowed IPs:

• Nooit 0.0.0.0/0. De add-on ondersteunt dat niet.
• Geen bereik dat het lokale netwerk van de klant overlapt. Dan stoppen lokale diensten zoals MQTT met werken.
• Heeft de klant een extra route nodig (bv. een host op jouw netwerk), voeg die als /32 toe achter 10.99.0.0/24.

Stap 4: tunnel controleren

De tunnel werkt pas als vier dingen kloppen. Loop ze in deze volgorde na.

1. Adres in het logboek. Er moet staan ip -4 address add 10.99.0.x/.... Staat er 10.6.0.2/24, dan is dat de standaardwaarde van de add-on en is je adres niet bewaard. Zet het opnieuw, sla op en herstart. Dit is bij de eerste tests meerdere keren gebeurd.
2. Route in het logboek. Er moet staan ip -4 route add 10.99.0.0/24 dev wg0.
3. Public key vergelijken. Na ongeveer 30 seconden toont de add-on een statusblok met zijn eigen public key. Die moet exact gelijk zijn aan de Public key van de peer in OPNsense. Is er een verschil, dan negeert OPNsense alle pakketten zonder foutmelding.
4. Handshake. In het statusblok moet latest handshake staan en received groter dan 0. In OPNsense onder VPN → WireGuard → Status moet de peer groen zijn met een Handshake Age.

Daarna testen met een ping naar het tunnel-IP van de klant, vanaf OPNsense (Interfaces → Diagnostics → Ping) en vanaf Gepetto of je computer. Werkt de ping vanaf OPNsense wel en vanaf je computer niet, dan klopt de NAT of de firewallregel op de WireGuard-interface niet.

Stap 5: firewall op de WireGuard-interface

Bij de eerste tests kan er een brede regel zijn aangemaakt (pass, source 10.99.0.0/24, destination any). Die hoort niet in productie.

De backup werkt als pull: Gepetto verbindt naar de klant, de klant verbindt nooit naar binnen. Daardoor heeft een klant op de WireGuard-interface geen enkele toegang tot je netwerk nodig.

1. Firewall → Rules → WireGuard (Group): verwijder de brede testregel.
2. Laat de interface zonder pass-regels staan. Alles wat een klant zelf start wordt dan geblokkeerd, ook naar andere klanten.
3. Verkeer dat jij zelf start (Gepetto, je computer) en het antwoord daarop blijft werken, want de firewall houdt de sessie bij.
4. Apply, en test opnieuw: ping en SSH vanaf Gepetto moeten blijven werken.

Heeft een klant ooit toegang nodig tot een dienst bij jou, maak dan een regel per peer-IP naar alleen dat IP en die poort.

Stap 6: backup via Gepetto

Gepetto haalt de nieuwste HA-back-up op via SSH over de tunnel, bewaart hem in /backupHosts/<klant> en zet hem met proxmox-backup-client op de PBS. Er is geen tweede server nodig en de klant heeft geen open poort of port forward meer nodig.

Bij de klant (Home Assistant)

1. Instellingen → Systeem → Back-ups: automatische back-up aan (bv. dagelijks), encryptie aan, lokaal weinig exemplaren bewaren. De bestanden komen in /backup/*.tar.
2. Bewaar de encryptiesleutel buiten HA, in je wachtwoordmanager. Zonder die sleutel is de back-up niet te herstellen.
3. Installeer een SSH-add-on (Terminal & SSH of Advanced SSH), stel een wachtwoord of een authorized_keys in en vul bij Netwerk een poort in. Een leeg poortveld betekent dat de poort niet naar buiten wordt gepubliceerd.

Vanaf Gepetto: eerst testen

ping -c3 <tunnel-ip>
nc -zv <tunnel-ip> 22 22222 8123
ssh -p <poort> root@<tunnel-ip> "ls -t /backup/*.tar | head -n1"

De poorten 11121 en 11122 zijn port forwards op routers van andere klanten. Op het tunnel-IP geven ze Connection refused. Gebruik de poort die de SSH-add-on echt publiceert.

Script per klant

1. mkdir -p /backupHosts/<klant>
2. Kopieer een bestaand script, bv. /diy/klericlaukensBackups.sh, naar /diy/<klant>Backups.sh.
3. Pas bovenaan aan:

backupnode="<klant>"
backupmap="/backupHosts/<klant>"
ha_server="<tunnel-ip>"
ha_port="<poort van de SSH-add-on>"

4. De rest van het script blijft gelijk: nieuwste .tar ophalen, lokale kopieën ouder dan 7 dagen wissen, back-up naar de PBS met --backup-id per klant.
5. Draai het één keer handmatig en plan het daarna zoals je bestaande klantscripts.

Aanbevolen, niet verplicht: een SSH-sleutel in plaats van sshpass met een wachtwoord in het script, en een PBS API-token met een eigen namespace in plaats van root@pam.

Stap 7: backup controleren

Een klant is pas klaar als de backup aantoonbaar aankomt en terug te zetten is.

1. /var/log/cloudbackup.log op Gepetto toont Laatste backup: ... en Cleanup uitgevoerd, zonder Downloaden mislukt.
2. Op de PBS staat een nieuwe snapshot met backup-id = de klantnaam.
3. Doe per klant minstens één restore-test: haal de .tar terug en controleer dat hij met de encryptiesleutel te openen is.
4. Controleer dat er geen backup ontbreekt: een eenvoudige check is dat er in de laatste twee dagen een bestand bijkwam.

find /backupHosts/<klant> -name '*.tar' -mtime -2 | grep -q . || echo "GEEN recente backup voor <klant>"

Laat die regel een melding sturen via de manier waarop je nu ook andere fouten opvangt.

De HA-backups zijn al gecomprimeerd en versleuteld. De PBS kan er weinig op dedupliceren, dus houd de retentie klein (het script bewaart 7 dagen lokaal).

Problemen oplossen

Wat je ziet	Meestal betekent het	Wat je doet
Add-on: sent loopt op, received blijft 0, peer in OPNsense rood	De public key in OPNsense is niet die van de klant, of de peer is niet aan de instance gekoppeld, of Apply ontbreekt	Public keys vergelijken (stap 4), peer selecteren bij de instance, Apply
Handshake is er, ping werkt niet	Het adres in de add-on staat op de standaardwaarde 10.6.0.2	Adres opnieuw instellen, opslaan, herstarten en in het logboek controleren
Peer in OPNsense rood, endpoint van de peer toont je eigen publieke IP	Bij de peer staat een endpoint ingevuld	Endpoint address en port leegmaken, Save, Apply
Eén peer groen, een andere rood, beide met dezelfde key	Eén keypair op twee toestellen	Nieuw keypair via de Peer generator voor het tweede toestel
Werkt bij de klant, niet vanuit je eigen netwerk	NAT-reflection op je eigen publieke IP	Voor de test het LAN-IP van OPNsense als endpoint gebruiken
Add-on: FATAL: You need a private_key configured	Het veld private key is leeg	Private key invullen
SSH: Connection refused	Er luistert niets op die poort	De poort van de SSH-add-on controleren (stap 6)
Geen verbinding, geen foutmelding	Endpoint niet ingevuld in de add-on	Endpoint invullen

Nog te verifiëren

Dit staat niet bevestigd en moet je bij de eerste echte klant controleren.

1. SSH over de tunnel. De test nc -zv <tunnel-ip> 22 22222 8123 is nog niet uitgevoerd. Het is niet bevestigd dat een SSH-add-on bereikbaar is op het tunnel-IP. Staat poort 8123 niet open, dan draait de WireGuard Client-add-on niet in het host-netwerk en moet de route naar de klant anders.
2. Adres dat terugspringt. Het interface-adres van de add-on stond eerder terug op 10.6.0.2/24. Controleer na elke wijziging het logboek.
3. Herstart van HA. Test of de tunnel na een herstart vanzelf terugkomt (start bij opstarten en watchdog aan in de add-on).
4. Lab-peer veoniriaxyz. Die had dezelfde public key als eroniriaxyz. Controleer dat de labmachine een eigen keypair heeft.
5. Brede firewallregel op de WireGuard-interface verwijderd (stap 5).
6. Wachtwoorden in scripts. Een SSH-wachtwoord en root@pam met wachtwoord staan in leesbare scripts. Vervang ze door een SSH-sleutel en een PBS API-token met eigen namespace.
7. SSH-poort per klant. Noteer in de tabel bovenaan welke poort de SSH-add-on van elke klant gebruikt.