The source post captures the core pieces needed to make a Tailscale Docker client on ZimaOS register with a self-hosted Headscale control plane: persistent state, a one-time/pre-auth key, the custom Headscale URL, TUN access, and the required container capabilities.
Current Tailscale and Headscale documentation now provide a clearer upstream contract. Tailscale officially supports a custom control server URL, and Headscale documents both interactive registration and pre-auth-key registration. Use those upstream methods to validate the current command/URL rather than relying only on a 2025 screenshot.
Headscale Replaces the Tailscale Coordination Control Plane
Headscale is a self-hosted implementation of the Tailscale control server protocol. Tailscale clients still create encrypted peer-to-peer tunnels, but registration and coordination are handled by the user's Headscale instance instead of the default Tailscale control plane.
Persist the Tailscale State Directory
The source created /DATA/AppData/tailscale/state and mapped it to /var/lib/tailscale. This is important because the node identity/state should survive container recreation and host reboot.
The source also recommended restrictive permissions on the host state directory. That is sensible because the state is part of the node's identity and should not be world-readable.
Use the Headscale URL as the Custom Control Server
Current Tailscale documentation supports custom control servers through:
tailscale login --login-server=<URL>Dokumentacja Headscale korzysta z tego samego modelu za pomocą tailscale up --login-server <YOUR_HEADSCALE_URL>.
Zobacz aktualne wskazówki Tailscale dotyczące niestandardowego serwera sterowania.
Użyj klucza wstępnej autoryzacji do rejestracji nieinteraktywnej
Źródło tymczasowo dodało TS_AUTHKEY, zarejestrowano węzeł, a następnie usunięto tę zmienną. Obecnie dokumentacja Headscale opisuje tworzenie klucza wstępnej autoryzacji i używanie go z --authkey w przypadku rejestracji nieinteraktywnej.
Użyj aktualnych metod rejestracji Headscale.
Nie pozostawiaj klucza uwierzytelniającego wielokrotnego użytku w definicji aplikacji
Jeśli klucz może być używany wielokrotnie lub ma długi okres ważności, pozostawienie go w środowisku aplikacji ZimaOS powoduje niepotrzebne narażenie. Po pomyślnym zapisaniu tożsamości węzła usuń sekret rejestracyjny, gdy nie jest już potrzebny.
Jeśli klucz został wklejony na publicznym forum lub pokazany na zrzucie ekranu, unieważnij go i utwórz nowy.
TUN jądra i uprawnienia wpływają na tryb sieciowy
Źródło mapuje /dev/net/tun oraz nadaje NET_ADMIN/NET_RAW, który korzysta ze stylu sieciowego opartego na jądrze, a nie z czystej sieci w przestrzeni użytkownika.
Aktualne kontenery Tailscale mogą również działać w trybie przestrzeni użytkownika, więc wybierz tryb świadomie, zależnie od tego, czy potrzebujesz routingu podsieci, działania jako węzeł wyjściowy czy pełnej obsługi sieci w jądrze.
Sieć hosta jest potężnym rozwiązaniem
Źródło używa sieci hosta Docker. Eliminuje to standardową izolację portów kontenera i sprawia, że Tailscale działa bezpośrednio w przestrzeni nazw sieci hosta.
Nie zmieniaj trybu z hosta na most ani odwrotnie bez zrozumienia, jak bieżąca aplikacja Tailscale przechowuje trasy, nasłuchuje połączeń i udostępnia usługi.
Adres URL Headscale powinien być niezawodnie dostępny i odpowiednio zabezpieczony
Samodzielnie hostowany serwer sterujący staje się kluczową infrastrukturą. Używaj stabilnego DNS, prawidłowej konfiguracji TLS oraz kopii zapasowych bazy danych i konfiguracji Headscale. Jeśli serwer sterujący przestanie działać, istniejące urządzenia równorzędne mogą przez pewien czas nadal się komunikować, ale nowe rejestracje i zmiany koordynacji będą niedostępne.
Źródło przedstawia działającą konfigurację, a nie umowę wsparcia IceWhale
Wpis nie zawiera potwierdzenia pracowników IceWhale. Jest to konfiguracja społeczności, która dobrze odpowiada koncepcjom Tailscale/Headscale, ale nadal powinna zostać przetestowana z aktualnym pakietem Tailscale dla ZimaOS.
FAQ dotyczące Headscale w ZimaOS
Czy klienci Tailscale mogą korzystać z niestandardowego serwera sterującego Headscale?
Tak. Aktualna dokumentacja Tailscale oficjalnie obsługuje niestandardowe adresy URL serwera sterującego.
Czy TS_AUTHKEY powinien pozostać w aplikacji na zawsze?
Nie. Źródło usuwało go po rejestracji, a długotrwałe sekrety rejestracyjne nie powinny być niepotrzebnie pozostawiane bez zabezpieczenia.
Dlaczego utrwalać /var/lib/tailscale?
Zachowuje tożsamość/stan węzła Tailscale podczas odtwarzania kontenera i ponownego uruchamiania.
