Tailscale op ZimaOS uitvoeren voor externe toegang

Als de Tailscale-app in ZimaOS wordt geïnstalleerd, maar je door op de WebUI te klikken gewoon teruggaat naar het ZimaOS-dashboard, betekent dat niet per se dat de Tailscale-container defect is. De communitythread uit november 2024 begon precies met dat symptoom in ZimaOS 1.2.5. De nuttige correctie was dat Tailscale voornamelijk wordt geconfigureerd via authenticatie, omgevingsvariabelen en de Tailscale-CLI, en niet via een conventionele applicatie-WebUI.

Het oorspronkelijke antwoord adviseerde het App Store-pakket te gebruiken en een Tailscale-authenticatiesleutel op te geven via TS_AUTHKEY. Een latere ZimaOS-thread uit 2025 bevestigde een andere werkende methode: installeer Tailscale en voer tailscale status open in de CLI de aanmeldings-URL die wordt teruggegeven en authenticeer de node. De huidige Tailscale Docker-documentatie ondersteunt zowel workflows op basis van authenticatiesleutels als op basis van aanmelden, en raadt daarnaast persistente status aan zodat de container na herstarts dezelfde node-identiteit behoudt.

Waarom de link naar de Tailscale-“WebUI” misleidend kan zijn

De oorspronkelijke gebruiker verwachtte dat de app na installatie een beheerpagina zou openen. In plaats daarvan keerde de browser terug naar de startpagina van ZimaOS.

De oorspronkelijke communityoplossing: gebruik TS_AUTHKEY

Het eerste antwoord zei dat het App Store-pakket kon werken door een Tailscale-authenticatiesleutel aan te maken en deze te plakken in:

TS_AUTHKEY

De huidige Tailscale-documentatie definieert nog steeds TS_AUTHKEY als omgevingsvariabele die wordt gebruikt om een Docker-container bij een tailnet te authenticeren.

Huidige referentie: Tailscale Docker-configuratieparameters.

Genereer de sleutel in de Tailscale-beheerconsole en behandel deze vervolgens als een geheim. Publiceer de sleutel niet in schermafbeeldingen, forumberichten, Git-opslagplaatsen of gedeelde Compose-bestanden.

Alternatief: authenticeren via de Tailscale-CLI

Een latere ZimaOS-communityoplossing gebruikte:

tailscale status

Toen de node nog niet was geauthenticeerd, gaf Tailscale een aanmeldings-URL terug. De gebruiker opende die URL in een browser en keurde het apparaat goed.

Afhankelijk van de geïnstalleerde container en de shellcontext moet je de opdracht mogelijk in de Tailscale-container uitvoeren in plaats van rechtstreeks op de ZimaOS-host.

Identificeer eerst de container:

docker ps --format '{{.Names}}' | grep -i tailscale

Voer vervolgens, indien nodig, het volgende uit:

docker exec -it TAILSCALE_CONTAINER tailscale status

Gebruik de werkelijke containernaam die door je systeem wordt weergegeven.

Tailscale-status behouden na herstarts

De huidige Tailscale-Dockerdocumentatie raadt aan het volgende in te stellen:

TS_STATE_DIR=/var/lib/tailscale

en die map koppelen aan permanente opslag op de host. Zonder permanente status kan een opnieuw gestarte of opnieuw aangemaakte container als een nieuw knooppunt worden geregistreerd in plaats van zijn eerdere identiteit te behouden.

Tailscale biedt ook:

TS_AUTH_ONCE=true

voor implementaties die alleen moeten worden geauthenticeerd wanneer de container geen bestaande status heeft.

Wat een actuele containerconfiguratie nodig heeft

Een minimale conceptuele Docker-configuratie bevat:

environment:
  - TS_AUTHKEY=YOUR_SECRET_KEY
  - TS_STATE_DIR=/var/lib/tailscale
  - TS_AUTH_ONCE=true

volumes:
  - /YOUR/ZIMAOS/PERSISTENT/PATH:/var/lib/tailscale

Het exacte hostpad en de aanvullende netwerk-/apparaatinstellingen zijn afhankelijk van de App Store-definitie van ZimaOS. Vervang een werkende, actuele appdefinitie niet door een oude CasaOS-YAML alleen omdat de thread uit 2024 naar een CasaOS-handleiding verwees.

Toegang tot ZimaOS verschilt van het adverteren van het volledige LAN

Er zijn twee veelvoorkomende doelen:

• Het Tailscale-knooppunt zelf bereiken: maak verbinding met het ZimaOS/Tailscale-knooppunt via het Tailscale-adres of de MagicDNS-naam.
• Andere apparaten op het ZimaOS-LAN bereiken: configureer het knooppunt als Tailscale-subnetrouter.

Het tweede doel is complexer. Volgens de huidige Tailscale-documentatie moet de router routes adverteren en moeten deze in de beheerconsole worden goedgekeurd.

Zie documentatie over Tailscale-subnetrouters.

Subnetroutering in een getailiseerde Tailscale-app op ZimaOS vereist extra instellingen

Een communityrapport uit 2026 over ZimaOS toonde een Tailscale-Dockercontainer die succesvol verbinding maakte, maar LAN-routes niet kon adverteren. Die configuratie gebruikte hostnetwerken, de geprivilegieerde modus en /dev/net/tun, maar subnetroutes verschenen nog steeds niet.

Dit is een belangrijke grens: een container die succesvol verbinding maakt met je tailnet is niet automatisch een werkende subnetrouter. Voor routering zijn kernel-/netwerkprivileges, doorsturen, route-advertenties en goedkeuring door een beheerder vereist.

Als je alleen op afstand toegang wilt tot ZimaOS zelf, schakel subnetroutering dan niet onnodig in.

Tailscale vereist geen SMB-gasttoegang

Het communityantwoord uit 2024 beweerde dat voor het delen van SMB-mappen gastrechten nodig waren om via de Tailscale-tunnel te werken. Dat mag niet worden veralgemeend tot een huidige vereiste van Tailscale.

Tailscale biedt netwerkconnectiviteit. SMB-verificatie blijft een onafhankelijke Samba-/Windows-/macOS-rechtenlaag. Een correct geconfigureerd benoemd SMB-account kan via een Tailscale-verbinding werken, net zoals via een LAN.

Gasttoegang kan een tijdelijke oplossing zijn geweest voor de specifieke CasaOS/ZimaOS-Samba-configuratie in die oudere discussie, maar is geen inherent vereiste van Tailscale.

Beveiligingsnotities

• Gebruik een beperkte/herbruikbare of tijdelijke verificatiesleutel, afhankelijk van je implementatiebehoeften.
• Houd verificatiesleutels uit schermafbeeldingen en repositories.
• Maak de status persistent, zodat de node zich niet steeds opnieuw registreert.
• Gebruik Tailscale-ACL's of grants om te bepalen welke tailnet-apparaten toegang hebben tot de ZimaOS-node.
• Stel het ZimaOS-dashboard niet rechtstreeks bloot aan het openbare internet alleen omdat externe toegang nodig is.

Checklist voor de Tailscale-installatie op ZimaOS

1. Installeer het huidige Tailscale-pakket uit de App Store.
2. Gebruik de WebUI-link van de app niet als primaire configuratiemethode.
3. Verifieer met TS_AUTHKEY of de Tailscale-CLI-inlog-URL.
4. Maak persistent /var/lib/tailscale met TS_STATE_DIR.
5. Controleer of de node in de Tailscale-beheerconsole verschijnt.
6. Voer uit tailscale status en bevestig dat de node verbonden is.
7. Test de toegang tot de ZimaOS-node voordat je subnetroutering probeert te configureren.
8. Als je het hele LAN nodig hebt, configureer en keur je subnetroutes afzonderlijk goed.

Veelgestelde vragen over ZimaOS en Tailscale

Waarom verwijst de Tailscale-WebUI-link terug naar ZimaOS?

De Tailscale-container wordt normaal geconfigureerd via omgevingsvariabelen, verificatie en CLI-opdrachten, in plaats van via een traditionele app-WebUI. In de oorspronkelijke discussiethread ontstond precies deze verwarring.

Wat is TS_AUTHKEY?

Dit is de Tailscale Docker-omgevingsvariabele die wordt gebruikt om de container bij je tailnet te verifiëren.

Waarom moet ik TS_STATE_DIR persistent maken?

Met persistente status behoudt de container zijn node-identiteit en verificatie tijdens herstarts of het opnieuw aanmaken ervan.

Heb ik subnetroutering nodig om op afstand toegang te krijgen tot ZimaOS?

Nee. Subnetroutering is alleen nodig wanneer de Tailscale-node verkeer moet routeren naar andere niet-Tailscale-apparaten op het lokale netwerk.

Heeft SMB de gastmodus nodig via Tailscale?

Nee, niet als algemene Tailscale-regel. SMB-accountverificatie staat los van Tailscale-netwerken.