Headscale: zatwierdzanie tras podsieci i exit node'ów
Ogłosiłeś trasę lub exit node, a w headscale nic się nie dzieje? Pokazuję, jak zatwierdzić je w v0.29.7 przez nodes approve-routes, włączyć autoApprovers i sprawdzić, co blokuje ruch.
Dlaczego ogłoszona trasa w headscale nic nie robi
Zatwierdzanie tras w headscale to krok, który w Tailscale wykonujesz w konsoli webowej, a tutaj w terminalu serwera. Samo tailscale set --advertise-routes albo --advertise-exit-node nie wystarczy, bo trasa czeka na zgodę administratora. Zgodę daje polecenie headscale nodes approve-routes, a stan sprawdzasz przez headscale nodes list-routes.
Dokumentacja headscale nazywa to podwójną zgodą (double opt-in): raz po stronie routera, raz po stronie serwera sterującego. Dopóki drugi krok się nie wydarzy, trasa jest tylko ogłoszona. Klienci jej nie dostają, więc ruch do sieci za routerem nigdzie nie trafia i nie widzisz żadnego błędu.
Poradnik dotyczy headscale v0.29.7, wydanego 30 października 2026 roku. To wydanie bezpieczeństwa i najnowsza stabilna wersja w dniu pisania. Minimalna wspierana wersja klienta Tailscale dla tej wersji to v1.80.0. Jeśli dopiero stawiasz serwer, zacznij od instalacji własnego serwera headscale, a potem wróć tutaj.
Pułapka wersji: polecenie headscale routes enable już nie istnieje
Wiele starszych poradników i wątków na forach każe użyć osobnej grupy poleceń headscale routes. W nowych wersjach to nie działa. Według pliku CHANGELOG wersja 0.26.0 (z 14 maja 2025) usunęła osobne API i CLI dla tras. Wpis brzmi: Route API and CLI has been removed. Trasami zarządza się teraz przez polecenia węzłów (nodes).
Dlatego najpierw sprawdź, jaką wersję masz na serwerze:
headscale versionJeśli widzisz 0.26.0 lub nowszą, używaj tylko headscale nodes list-routes i headscale nodes approve-routes. Jeśli headscale działa w kontenerze Docker, poprzedź każde polecenie docker exec <nazwa-kontenera>, na przykład docker exec headscale headscale nodes list-routes.
Krok 1: ogłoś podsieć na routerze
Przykład w tym poradniku to sieć domowa lub firmowa za routerem MikroTik. Większość fabrycznych konfiguracji MikroTika ustawia na interfejsie LAN adres 192.168.88.1/24. Sieć, którą ogłaszasz, to więc 192.168.88.0/24, czyli adres sieci, a nie adres routera. Twoja sieć mogła zostać zmieniona, więc sprawdź ją. Na MikroTiku polecenie /system default-configuration print pokazuje konfigurację domyślną, którą router zastosował.
Na urządzeniu, które ma być routerem podsieci (subnet router) i jest już zarejestrowane w headscale, uruchom:
sudo tailscale set --advertise-routes=192.168.88.0/24Przy nowej rejestracji możesz zrobić to od razu:
sudo tailscale up --login-server https://headscale.example.com --advertise-routes=192.168.88.0/24Router podsieci przekazuje ruch w imieniu innych węzłów, więc potrzebuje włączonego przekazywania pakietów (IP forwarding). Bez niego trasa może być zatwierdzona, a pakiety i tak giną na routerze. Konfigurację forwardingu na Linuksie opisuje poradnik o routerze podsieci Tailscale na VPS. Kroki po stronie klienta Tailscale są te same, zmienia się tylko serwer sterujący.
Krok 2: sprawdź trasę poleceniem headscale nodes list-routes
Na serwerze headscale wyświetl trasy wszystkich węzłów:
headscale nodes list-routesWynik ma kolumny ID | Hostname | Approved | Available | Serving (Primary). Zaraz po ogłoszeniu wygląda mniej więcej tak:
ID | Hostname | Approved | Available | Serving (Primary)
1 | mikrotik | | 192.168.88.0/24 |Kolumny oznaczają różne stany tej samej trasy:
- Available: router ogłosił tę trasę.
- Approved: administrator ją zatwierdził.
- Serving (Primary): headscale rozsyła ją klientom, a ten węzeł obsługuje ruch.
Pusta kolumna Approved przy wypełnionej Available to dokładnie sytuacja „ogłosiłem i nic się nie dzieje”. Zapamiętaj liczbę z kolumny ID. Jest potrzebna w następnym kroku.
Krok 3: zatwierdź trasę poleceniem approve-routes
headscale nodes approve-routes --identifier 1 --routes 192.168.88.0/24Headscale odpowiada Node updated. Uruchom ponownie headscale nodes list-routes. Prefiks 192.168.88.0/24 powinien teraz stać w kolumnach Approved, Available i Serving.
Jeśli węzeł ogłasza kilka sieci, podaj je po przecinku, bez spacji: --routes 192.168.88.0/24,10.10.0.0/16. Dokumentacja nie opisuje, co dzieje się z wcześniej zatwierdzonymi trasami, gdy w kolejnym wywołaniu podasz krótszą listę. Dlatego po każdej zmianie sprawdzaj wynik w list-routes, zamiast zakładać.
Gdy ten sam prefiks ogłaszają co najmniej dwa węzły, headscale sam włącza tryb wysokiej dostępności (HA) dla tej trasy. Ustawienia tego trybu są w config.yaml w sekcji node.routes.ha.
Krok 4: klient Linux musi przyjąć trasy
To najczęstszy powód, dla którego zatwierdzona trasa nadal nie działa. Klient Tailscale na Linuksie domyślnie nie przyjmuje tras podsieci. Domyślnie przyjmują je Windows, iOS, Android i obie wersje na macOS. Na każdym linuksowym kliencie, który ma widzieć sieć za routerem, uruchom:
sudo tailscale set --accept-routes
ping -c 3 192.168.88.1Odpowiedzi z 192.168.88.1 oznaczają, że ruch idzie przez tunel do routera podsieci i dalej do LAN-u. Brak odpowiedzi przy zatwierdzonej trasie wskazuje na forwarding albo zaporę na routerze podsieci. Jeśli chcesz zrozumieć, dlaczego klient wysyła pakiet akurat do tego węzła, przeczytaj jak WireGuard wiąże adresy IP z kluczami (cryptokey routing). Tailscale buduje na tym mechanizmie.
Exit node w headscale: ogłoszenie, zatwierdzenie, użycie
Węzeł wyjściowy (exit node) wypuszcza do internetu cały ruch klienta. Typowe zastosowanie to VPS w Polsce, przez który łączysz się z laptopa w podróży, żeby mieć polski adres IP. Ścieżka jest ta sama co dla podsieci, tylko trasy to 0.0.0.0/0 i ::/0.
Na węźle wyjściowym:
sudo tailscale set --advertise-exit-nodePrzy nowej rejestracji dokumentacja headscale podaje wariant sudo tailscale up --login-server https://headscale.example.com --advertise-exit-node. Linux musi mieć włączony IP forwarding, inaczej nie będzie działał jako exit node. Forwarding i reguły UFW na VPS opisuje poradnik o węźle wyjściowym Tailscale na VPS.
Dokumentacja Tailscale dla ich własnego serwera mówi, że po tailscale set --advertise-exit-node trzeba jeszcze uruchomić tailscale up. Dokumentacja headscale tego kroku nie pokazuje. Trzymaj się wersji headscale i sprawdź wynik na serwerze, zamiast uruchamiać gołe tailscale up na węźle zarejestrowanym we własnym serwerze.
Na serwerze sprawdź trasy i zatwierdź jedną z nich:
headscale nodes list-routes
headscale nodes approve-routes --identifier 2 --routes 0.0.0.0/0Wystarczy zatwierdzić trasę IPv4 albo IPv6. Druga zostanie zatwierdzona automatycznie. Po tym list-routes pokazuje obie trasy jako Approved, Available i Serving.
Na kliencie wybierz węzeł wyjściowy po nazwie albo po adresie Tailscale:
sudo tailscale set --exit-node myexit
curl -4 https://ifconfig.mecurl powinien zwrócić publiczny adres IP węzła wyjściowego, a nie adres Twojego łącza. Żeby przestać używać węzła, uruchom sudo tailscale set --exit-node=. Opcjonalna flaga --exit-node-allow-lan-access=true zostawia dostęp do lokalnej sieci, na przykład do drukarki w hotelu.
Kto może używać exit node'a
W v0.29.7 bez załadowanej polityki headscale przepuszcza cały ruch między węzłami. Wtedy każdy węzeł w sieci może wybrać i użyć każdego węzła wyjściowego. Tak samo każdy węzeł może przyjąć i używać każdej zatwierdzonej trasy podsieci.
Z polityką o dostępie do internetu przez exit node decyduje reguła, której celem jest autogroup:internet. Ta autogrupa może stać tylko w miejscu celu (dst). Headscale obsługuje zarówno ACL, jak i grants. Zaleca grants, bo ACL uważa za starsze rozwiązanie. Przykład w formie grants:
{
"grants": [
{
"src": ["alice@"],
"dst": ["autogroup:internet"],
"ip": ["*"]
}
]
}Ta reguła pozwala użytkownikowi alice@ korzystać z dowolnego dostępnego węzła wyjściowego. Pod polityką to właśnie taka reguła ustala, kto może wychodzić do internetu przez exit node.
Automatyczne zatwierdzanie: autoApprovers i tagi
Ręczne approve-routes wystarcza przy jednym routerze. Przy kilku węzłach wygodniej, żeby headscale sam zatwierdzał trasy od zaufanych tagów. Służy do tego sekcja autoApprovers w pliku polityki. W przykładach z dokumentacji tagi są zdefiniowane w tagOwners:
{
"tagOwners": {
"tag:router": ["alice@"],
"tag:exit": ["alice@"]
},
"autoApprovers": {
"routes": {
"192.168.88.0/24": ["tag:router"]
},
"exitNode": ["tag:exit"]
}
}Plik polityki wskazujesz w config.yaml w sekcji policy (mode: file oraz path ze ścieżką do pliku). Router rejestruje się z tagiem i trasą:
sudo tailscale up --login-server https://headscale.example.com --advertise-tags tag:router --advertise-routes 192.168.88.0/24Dla węzła wyjściowego zamieniasz to na --advertise-tags tag:exit --advertise-exit-node. Trasa pojawia się wtedy jako Approved bez ręcznego kroku na serwerze. Sprawdź to w headscale nodes list-routes.
Uwaga na jedną rzecz w v0.29.7. Polityka powyżej nie ma sekcji acls ani grants. Według dokumentacji headscale traktuje taki plik jak politykę „wszystko dozwolone”. Działa więc tak jak brak polityki. W zapowiadanej wersji 0.30.0 to się zmienia, o czym niżej.
Nie działa albo brak internetu: lista kontrolna
Przejdź punkty po kolei. Każdy wyklucza jedną przyczynę.
- Trasa jest w Available, ale nie w Approved. Serwer nie dał zgody. Uruchom
headscale nodes approve-routesz właściwym ID i prefiksem. - Trasa jest zatwierdzona, ale klient jej nie przyjął. Na Linuksie brakuje
sudo tailscale set --accept-routes. Dotyczy to tras podsieci, nie wyboru exit node'a. - Trasa działa do routera, ale nie dalej, albo exit node nie wypuszcza ruchu. Brakuje IP forwarding lub zapora (UFW) blokuje przekazywanie na węźle wyjściowym. Ten przypadek opisuje poradnik o exit node na VPS podlinkowany wyżej.
- Pod polityką klient nie może użyć exit node'a. Polityka nie ma reguły z celem
autogroup:internetdla tego użytkownika lub tagu. - Ping po adresie IP działa, ale nazwy się nie rozwiązują. To problem DNS. Opis niżej.
Dokumentacja headscale v0.29.7 nie mówi wprost, czym klient rozwiązuje nazwy przy aktywnym exit node. Przykładowa konfiguracja podaje za to trzy ustawienia, które możesz sprawdzić. Po pierwsze, ustawienia DNS z headscale działają tylko na klientach z włączonym --accept-dns=true. Po drugie, override_local_dns decyduje, czy DNS z headscale zastępuje lokalne ustawienia węzła, a przykładowa konfiguracja ma tu true. Po trzecie, serwery, które headscale przekazuje klientom, są w dns.nameservers.global (w przykładzie to 1.1.1.1, 1.0.0.1 i dwa adresy IPv6). Sprawdź te trzy miejsca, a potem przetestuj rozwiązywanie nazwy na kliencie z włączonym exit node'em. Podobny objaw w czystym WireGuardzie rozbiera poradnik o naprawie DNS przez WireGuard.
Jeśli klient jest starszy niż v1.80.0, zaktualizuj go przed dalszym szukaniem. To minimalna wersja wspierana przez headscale 0.29.7.
Otwarte pytanie: dodatek Mullvad a headscale
Tailscale sprzedaje płatny dodatek z węzłami wyjściowymi Mullvad. Kupuje się go w konsoli administracyjnej Tailscale. Strona Tailscale o tym dodatku nie wspomina o headscale ani o innych serwerach sterujących. Strony dokumentacji headscale o trasach, polityce i DNS też nie wspominają o Mullvad. Nie da się więc dziś na podstawie dokumentacji powiedzieć, czy to działa z headscale. Jeśli potrzebujesz wyjścia do internetu z innego miejsca, pewną drogą jest własny exit node na VPS opisany wyżej.
Co zmieni się w headscale 0.30.0 (jeszcze niewydane)
Na gałęzi main CHANGELOG ma sekcję 0.30.0 (202x-xx-xx). To nagłówek bez daty, nie wydanie. Poniższe punkty to zapowiedzi, nie obecne zachowanie v0.29.7:
- API tras i
autoApprovers.routesodrzucą prefiksy z ustawionymi bitami hosta.10.0.0.1/24trzeba zapisać jako10.0.0.0/24. Dlatego w tym poradniku od początku jest192.168.88.0/24, nigdy192.168.88.1/24. Adres sieci jest poprawnym zapisem w obu wersjach. - Wycofanie trasy przez router usunie ją tylko wtedy, gdy była zatwierdzona wyłącznie automatycznie. Ręczne zatwierdzenia i zatwierdzenia sprzed aktualizacji zostają, a istniejące zatwierdzenia liczą się jako ręczne.
- Trasy wyjściowe będą wymagały dostępu do adresu w internecie. Reguły tylko do adresów prywatnych przestaną oferować exit node, a granty typu
appnigdy go nie oferują. - Polityka bez
aclsi bezgrantsprzestanie znaczyć „wszystko dozwolone”. Według notatek pozwoli tylko na adresy w sieci tailnet i zatwierdzone trasy. Jeśli Twój plik ma tylkotagOwnersiautoApprovers, przed aktualizacją dopisz jawne reguły dostępu, w tym regułę zautogroup:internetdla exit node'ów. - Minimalna wspierana wersja klienta Tailscale wzrośnie do v1.84.0.
Przed aktualizacją przeczytaj sekcję BREAKING w notatkach wydania, które faktycznie się ukaże. Zapowiedzi na gałęzi main mogą się jeszcze zmienić.
FAQ
Czym zastąpiono polecenie headscale routes enable?
Od wersji 0.26.0 headscale nie ma osobnego API ani CLI dla tras. Trasy wyświetlasz poleceniem headscale nodes list-routes, a zatwierdzasz poleceniem headscale nodes approve-routes --identifier <ID> --routes <prefiksy>. Prefiksy podajesz po przecinku. Serwer odpowiada Node updated, a trasa pojawia się w kolumnach Approved i Serving.
Trasa jest zatwierdzona, a klient Linux nie widzi sieci za routerem. Dlaczego?
Klient Tailscale na Linuksie domyślnie nie przyjmuje tras podsieci, w przeciwieństwie do Windows, iOS, Androida i macOS. Uruchom na nim sudo tailscale set --accept-routes i sprawdź ping do adresu w tej sieci. Jeśli nadal brak odpowiedzi, sprawdź IP forwarding i zaporę na routerze podsieci.
Czy muszę zatwierdzać osobno 0.0.0.0/0 i ::/0 dla exit node'a?
Nie. Według dokumentacji headscale v0.29.7 wystarczy zatwierdzić jedną z tych tras, na przykład headscale nodes approve-routes --identifier 2 --routes 0.0.0.0/0. Druga zostanie zatwierdzona automatycznie. W headscale nodes list-routes obie pojawią się jako Approved.
Kto może używać exit node'a w headscale?
W v0.29.7 bez załadowanej polityki każdy węzeł może wybrać każdy exit node. Gdy używasz polityki, o dostępie decyduje reguła z celem autogroup:internet, na przykład grant ze źródłem alice@ i "ip": ["*"]. Headscale zaleca zapis w formie grants zamiast starszych ACL.
Czy dodatek Mullvad z Tailscale działa z headscale?
Tego nie wiadomo z dokumentacji. Dodatek kupuje się w konsoli administracyjnej Tailscale, a ani Tailscale, ani headscale nie opisują jego użycia z własnym serwerem sterującym. Jeśli potrzebujesz wyjścia do internetu z innym adresem IP, postaw własny exit node na VPS i zatwierdź go w headscale.