Headscale ACL: przykłady polityk z grants krok po kroku
Headscale bez polityki przepuszcza cały ruch między węzłami. Zbuduj plik HuJSON z grupami, tagami, grants, regułą SSH i testami, sprawdzony na wersji 0.29.7.
Polityka ACL w headscale: dlaczego to pilne
Polityka ACL w headscale to plik HuJSON, który określa, które urządzenia w Twojej sieci mogą łączyć się z którymi. Dopóki go nie ma, headscale przepuszcza cały ruch między węzłami. Laptop stażysty widzi więc bazę danych tak samo jak Twój serwer. Poniżej budujemy taką politykę od zera, krok po kroku. Główną formą są reguły typu grants.
ACL (access control list) to lista kontroli dostępu. HuJSON to zwykły JSON, w którym wolno dodatkowo pisać komentarze i stawiać przecinki na końcu listy. Wszystkie przykłady poniżej są poprawnym JSON-em, więc działają też jako HuJSON.
Zakładamy, że headscale już u Ciebie działa, na przykład według naszego poradnika własny serwer koordynacyjny Tailscale z headscale. Wszystko sprawdziliśmy w dokumentacji i kodzie wersji v0.29.7 z 30 października 2026. To wydanie poprawiające bezpieczeństwo. Najstarsza obsługiwana wersja klienta Tailscale to v1.80.0. Opiekunowie projektu zalecają v1.104.4 lub nowszą, szczególnie jeśli używasz Tailscale SSH. Reguły grants są dostępne od headscale 0.29.0, więc starsza wersja nie zrozumie przykładów z tego tekstu. Jeśli masz inną wersję, czytaj dokumentację dla swojego tagu, a nie stronę „stable”. Dla 0.29.7 jest to headscale.net/0.29.7/ref/policy.
Co headscale robi, gdy polityki nie ma albo jest pusta
Dokumentacja 0.29.7 mówi wprost: domyślnie żadna polityka nie jest wczytana, więc headscale pozwala na cały ruch między węzłami. Warto znać na pamięć cztery przypadki, bo różnią się jednym znakiem:
- Brak pliku albo pusta ścieżka
policy.path: wszystko jest dozwolone. - Plik z samym
{}, czyli bez sekcjiaclsi bez sekcjigrants: też wszystko jest dozwolone. - Plik
{ "grants": [] }, czyli pusta lista grants: wszystko jest zablokowane. - Plik z co najmniej jednym grantem: dozwolone jest tylko to, co otwierają granty.
To pokazuje, jak działają grants. Każdy grant otwiera jedną drogę. Ruch, którego żaden grant nie otwiera, jest blokowany. Dlatego pierwszy grant, który dodasz, od razu zamyka wszystko inne. Zaplanuj go tak, żeby nie odciąć samego siebie.
Dokumentacja zaleca grants i nazywa składnię acls przestarzałą (legacy), bo Tailscale nie będzie już dodawać do niej nowych funkcji. Obie formy nadal działają, a od 0.29.0 można je mieszać w jednym pliku. Tutaj uczymy grants. Starą składnię pokazujemy tylko raz, żeby dało się czytać starsze przykłady z internetu.
Jak włączyć plik polityki w config.yaml
Headscale czyta politykę z pliku albo z bazy danych. Decyduje o tym klucz policy.mode, który przyjmuje wartość file albo database. W trybie file klucz policy.path wskazuje plik HuJSON. Przykładowy config-example.yaml z tagu v0.29.7 ma mode: file i pustą ścieżkę path: "", czyli brak polityki.
Otwórz plik konfiguracji headscale (w instalacji z pakietu zwykle /etc/headscale/config.yaml) i ustaw ścieżkę:
policy:
mode: file
path: /etc/headscale/policy.hujsonZanim zrestartujesz serwer, utwórz plik polityki. Na początek wpisz do niego {}. Ruch się nie zmieni, bo pusty obiekt nadal oznacza „wszystko dozwolone”. Sprawdzisz za to, że headscale znajduje plik.
echo '{}' | sudo tee /etc/headscale/policy.hujson
sudo systemctl restart headscale
sudo systemctl status headscale --no-pagerStatus powinien pokazać active (running). Jeśli usługa nie startuje, przeczytaj ostatnie linie dziennika poleceniem sudo journalctl -u headscale -n 50 --no-pager. Najczęstsza przyczyna to literówka w ścieżce albo w nazwie klucza.
Pętla edycji: policy check, reload, policy get
Każdą zmianę polityki wprowadzaj w tej samej kolejności. Najpierw sprawdzasz plik. Potem przeładowujesz serwer. Na końcu czytasz dziennik.
sudo headscale policy check -f /etc/headscale/policy.hujson
sudo systemctl reload headscale
sudo journalctl -u headscale -n 20 --no-pager
sudo headscale policy getheadscale policy check sprawdza plik, zanim zobaczy go serwer. Domyślnie łączy się przez gRPC z działającym serwerem i sprawdza politykę na prawdziwych użytkownikach i węzłach. gRPC to mechanizm zdalnych wywołań, którym CLI headscale rozmawia z serwerem. Poprawny plik kończy się komunikatem Policy is valid. Kod źródłowy i notatki do wydania 0.29.0 opisują jednak różnie, czy w tym trybie wykonuje się blok tests. Notatki wiążą testy z flagą --bypass-grpc-and-access-database-directly. Ta flaga otwiera bazę bezpośrednio i pyta, czy headscale na pewno nie działa. Nie używaj jej przy działającym serwerze. Sprawdź headscale policy check --help na swoim systemie. Testy i tak wykonają się przy przeładowaniu, o czym piszemy niżej.
W trybie file zmiany w pliku nie zaczynają działać same. Headscale trzeba przeładować: sudo systemctl reload headscale albo sygnałem SIGHUP wysłanym do głównego procesu. Headscale zapisuje w dzienniku wynik każdego przeładowania. Dlatego po reload zawsze czytasz journalctl. Tam zobaczysz błąd składni albo nieudany test.
headscale policy get wypisuje bieżącą politykę. Uwaga na pułapkę: w trybie file to polecenie czyta plik z dysku i zwraca jego treść bez zmian. Jeśli zapomnisz o przeładowaniu, policy get pokaże nowy plik, a serwer nadal będzie stosował starą politykę. Prawdziwym potwierdzeniem jest wpis w dzienniku i test połączenia z klienta.
Krok 1: grupy i tagOwners
Użytkownik w polityce headscale ma postać nazwa@: nazwa użytkownika z headscale i znak @ na końcu, bez domeny. Headscale odrzuca nazwę bez @ z błędem username must contain @. Nazwy użytkowników sprawdzisz poleceniem sudo headscale users list.
Weźmy małą firmę albo rozbudowany homelab. Ania administruje serwerami. Bartek i Kasia piszą kod i potrzebują bazy PostgreSQL. Serwer bazy to osobny węzeł.
{
"groups": {
"group:admin": ["ania@"],
"group:dev": ["bartek@", "kasia@"]
},
"tagOwners": {
"tag:db": ["group:admin"],
"tag:exit": ["group:admin"]
}
}Sekcja groups łączy użytkowników w grupy. Nazwa grupy zawsze zaczyna się od group:. Sekcja tagOwners określa, kto może nadać dany tag. Tag opisuje rolę serwera, a nie osobę. Reguły piszesz więc dla tag:db, a nie dla konkretnego komputera.
Ten plik nie ma jeszcze ani acls, ani grants, więc ruch nadal jest w pełni otwarty. To dobry moment, żeby oznaczyć serwer bazy tagiem. Znajdź jego ID w wyniku sudo headscale nodes list i nadaj tag:
sudo headscale nodes tag -i 3 -t tag:dbZamień 3 na ID swojego węzła. Węzeł z tagiem przestaje być urządzeniem osobistym użytkownika. Dokumentacja tagów nazywa to konwersją węzła osobistego na węzeł otagowany. Ma to znaczenie w kroku 3, bo autogroup:self opisuje urządzenia tego samego użytkownika.
Krok 2: grant dla grupy dev tylko do bazy na jednym porcie
Grant ma trzy pola. src to źródło ruchu, dst to cel, a ip to lista protokołów i portów. Wartość "tcp:5432" oznacza TCP na porcie 5432, czyli domyślnym porcie PostgreSQL. Wartość "*" oznacza wszystkie porty, razem z TCP, UDP i ICMP. Pełną składnię pola ip opisuje dokumentacja Tailscale o składni grants.
{
"grants": [
{
"src": ["group:dev"],
"dst": ["tag:db"],
"ip": ["tcp:5432"]
},
{
"src": ["group:admin"],
"dst": ["tag:db", "tag:exit"],
"ip": ["*"]
}
]
}Dopisz te reguły do pliku z kroku 1, obok groups i tagOwners. Pierwszy grant pozwala Bartkowi i Kasi łączyć się z bazą tylko na porcie 5432. SSH, panel administracyjny i każdy inny port na tym serwerze są dla nich zamknięte, bo nic ich nie otwiera. Drugi grant daje Ani pełny dostęp do serwerów z tagami. Bez niego po przeładowaniu Ania straciłaby dostęp do własnej bazy przez sieć tailnet.
Jeśli wpiszesz port z dwoma dwukropkami, na przykład "tcp:5432:1", headscale odrzuci plik z błędem expected only one colon in Internet protocol and port type. Po przeładowaniu sprawdź połączenie z laptopa Bartka:
nc -zv -w 3 100.64.0.3 5432
nc -zv -w 3 100.64.0.3 22Adres zamień na adres węzła bazy z headscale nodes list. Pierwsze polecenie powinno zgłosić udane połączenie. Drugie nie powinno nawiązać połączenia i zakończy się po upływie limitu 3 sekund albo błędem. Port 22 nie jest otwarty dla grupy dev.
Krok 3: własne urządzenia i exit node przez autogroup:internet
Od chwili, gdy plik ma choć jeden grant, laptop Ani nie widzi już jej własnego telefonu, bo nic tego ruchu nie otwiera. Rozwiązaniem jest autogroup:self, czyli „urządzenia tego samego użytkownika”. Można go używać tylko jako celu (dst):
{
"src": ["autogroup:member"],
"dst": ["autogroup:self"],
"ip": ["*"]
}autogroup:member oznacza wszystkie urządzenia osobiste, czyli bez tagów. Każdy użytkownik dostaje więc dostęp do swoich urządzeń, ale nie do cudzych. Dokumentacja ostrzega, że autogroup:self może obniżyć wydajność w dużych wdrożeniach. Wtedy proponuje osobny grant dla każdego użytkownika, na przykład "src": ["ania@"], "dst": ["ania@"].
Druga typowa potrzeba to exit node, czyli węzeł, przez który wychodzi ruch do internetu. Sam exit node konfigurujesz po stronie klienta Tailscale. Opisaliśmy to w tekście o tym, jak zrobić z VPS-a exit node Tailscale. Polityka decyduje tylko o tym, kto może z niego korzystać:
{
"src": ["group:admin"],
"dst": ["autogroup:internet"],
"ip": ["*"]
}autogroup:internet oznacza dostęp do internetu przez exit node i może stać tylko w dst. W tym przykładzie Ania może wysyłać ruch do internetu przez exit node, a grupa dev nie może.
Krok 4: reguła SSH z autogroup:nonroot
Tailscale SSH to logowanie przez SSH, w którym tożsamość pochodzi z sieci tailnet, a nie z kluczy w authorized_keys. Takie reguły trafiają do osobnej sekcji ssh. Mają pola action, src, dst i users:
{
"ssh": [
{
"action": "accept",
"src": ["group:admin"],
"dst": ["tag:db"],
"users": ["autogroup:nonroot"]
}
]
}autogroup:nonroot w polu users oznacza dowolne konto lokalne oprócz root. Ania może więc zalogować się na serwer bazy jako ubuntu albo postgres, ale nie jako root. Tej autogrupy można użyć tylko w polu users reguł SSH. Serwer docelowy musi mieć włączone Tailscale SSH po stronie klienta Tailscale. Strona polityki headscale nie opisuje reguł SSH szczegółowo i odsyła do dokumentacji Tailscale SSH.
Jeśli używasz acceptEnv, czyli listy zmiennych środowiskowych przekazywanych do sesji, potrzebujesz co najmniej 0.29.7. Według notatek do tego wydania wcześniej to ustawienie nie miało żadnego efektu.
Krok 5: blok tests, który odrzuca złą zmianę
Blok tests to lista twierdzeń o tym, kto ma się dokąd dostać. Od 0.29.0 headscale wykonuje go przy headscale policy set, przy przeładowaniu przez SIGHUP i przy headscale policy check. Jeśli test nie przechodzi, zmiana jest odrzucana, zanim zacznie działać. Funkcja ma status beta.
{
"tests": [
{
"src": "bartek@",
"proto": "tcp",
"accept": ["tag:db:5432"],
"deny": ["tag:db:22"]
},
{
"src": "ania@",
"proto": "tcp",
"accept": ["tag:db:22", "tag:db:5432"]
}
]
}Każdy test ma jedno źródło w polu src. To pojedynczy napis, a nie lista. accept to cele, do których ruch musi przejść. deny to cele, które muszą być zablokowane. Test musi mieć co najmniej jedno z tych dwóch pól. proto może być puste albo mieć wartość tcp, udp lub sctp. Każdy cel to jeden host i jeden port w formie host:port. Zakres portów, adres CIDR ani autogroup:internet nie przejdą.
Gdy ktoś później poszerzy grant dla grupy dev do "*", dziennik po przeładowaniu pokaże linię kończącą się na expected DENIED, got ALLOWED, a zmiana nie zostanie zastosowana. Odwrotny błąd kończy się na expected ALLOWED, got DENIED. Test, którego cel nie ma żadnego adresu, na przykład tag bez ani jednego węzła, kończy się błędem destination resolved to no IP addresses. Test z użytkownikiem, którego nie ma w headscale, też nie przejdzie.
Jedna rzecz zaskakuje. Przy starcie serwera zapisana polityka, której testy już nie przechodzą, nie zatrzymuje headscale. Serwer zapisuje ostrzeżenie w dzienniku i działa dalej. Tak może się stać, gdy usuniesz użytkownika przy wyłączonym serwerze. Po restarcie zawsze więc zajrzyj do journalctl.
Cała polityka w jednym pliku
Oto wszystkie kroki razem. Zapisz to jako /etc/headscale/policy.hujson, a potem przejdź pętlę edycji opisaną wyżej.
{
"groups": {
"group:admin": ["ania@"],
"group:dev": ["bartek@", "kasia@"]
},
"tagOwners": {
"tag:db": ["group:admin"],
"tag:exit": ["group:admin"]
},
"grants": [
{
"src": ["autogroup:member"],
"dst": ["autogroup:self"],
"ip": ["*"]
},
{
"src": ["group:dev"],
"dst": ["tag:db"],
"ip": ["tcp:5432"]
},
{
"src": ["group:admin"],
"dst": ["tag:db", "tag:exit"],
"ip": ["*"]
},
{
"src": ["group:admin"],
"dst": ["autogroup:internet"],
"ip": ["*"]
}
],
"ssh": [
{
"action": "accept",
"src": ["group:admin"],
"dst": ["tag:db"],
"users": ["autogroup:nonroot"]
}
],
"tests": [
{
"src": "bartek@",
"proto": "tcp",
"accept": ["tag:db:5432"],
"deny": ["tag:db:22"]
},
{
"src": "ania@",
"proto": "tcp",
"accept": ["tag:db:22", "tag:db:5432"]
}
]
}Zwróć uwagę, czego tu nie ma. Bartek nie połączy się z laptopem Kasi i odwrotnie, bo autogroup:self obejmuje tylko własne urządzenia, a żaden inny grant tego nie otwiera. Jeśli zespół potrzebuje takiego ruchu, dopisz osobny grant z konkretnym portem. Jeśli za jednym węzłem stoi cała prywatna podsieć, reguły piszesz dla jej adresów. Sam węzeł konfigurujesz tak jak w poradniku o tym, jak udostępnić prywatną sieć przez subnet router Tailscale.
Stara składnia acls, żeby czytać starsze przykłady
W wielu poradnikach zobaczysz sekcję acls. Pierwszy grant z kroku 2 wygląda w niej tak:
{
"acls": [
{
"action": "accept",
"src": ["group:dev"],
"proto": "tcp",
"dst": ["tag:db:5432"]
}
]
}Różnica leży w zapisie portu. W acls port jest doklejony do celu (tag:db:5432), a protokół jest w osobnym polu proto. W grants cel to sam tag:db, a protokół i port są w polu ip. Gdy przepisujesz stary przykład, przenieś port z dst do ip.
Panel WWW, np. Headplane, potrzebuje trybu database
Dokumentacja headscale mówi, że trzymanie polityki w bazie danych jest zwykle potrzebne tylko wtedy, gdy używasz interfejsu WWW. Headplane, panel WWW dla headscale, pisze w swojej dokumentacji, że zapisuje politykę tylko wtedy, gdy headscale działa w trybie database. W trybie file strona polityki w Headplane jest tylko do odczytu i wyświetla wyjaśnienie. Sprawdź dokumentację Headplane dla swojej wersji.
Tryb database zmienia pętlę edycji. Ustawiasz mode: database, restartujesz headscale i wgrywasz politykę poleceniem:
sudo headscale policy set -f /etc/headscale/policy.hujson
sudo headscale policy getheadscale policy set działa tylko w trybie database. W trybie file serwer zwraca błąd update is disabled for modes other than 'database'. Nie kieruj się tu tekstem pomocy tego polecenia. W 0.29.7 opis polecenia set w kodzie CLI headscale, wyświetlany przez headscale policy set --help, nadal mówi, że polecenie działa tylko przy acl.policy_mode ustawionym na "db". Taki klucz nie istnieje w config.yaml. Prawdziwy klucz to policy.mode z wartością database. W tym trybie policy get czyta politykę z bazy, więc pokazuje to, co naprawdę zapisano.
Czego headscale nie przenosi z Tailscale
Headscale obsługuje dużą część formatu polityki Tailscale, ale nie całość. Według dokumentacji 0.29.7 nie działają:
- Device postures, czyli sekcja
posturesi polesrcPosture. Nie uzależnisz dostępu od stanu urządzenia. - IP sets.
- Autogrupy spoza listy headscale. Dostępne są tylko
autogroup:internet,autogroup:member,autogroup:tagged,autogroup:self,autogroup:nonrootiautogroup:danger-all.
autogroup:danger-all oznacza wszystkie adresy IP, także spoza sieci tailnet, i może stać tylko w src. Nazwa nie jest przypadkowa, więc używaj jej świadomie. Jeśli kopiujesz politykę z dokumentacji Tailscale, najpierw porównaj każdą autogrupę z tą listą.
Model zagrożeń: czego polityka nie chroni
Polityka filtruje ruch między węzłami. Nic więcej nie robi. Nie chroni przed dwiema sytuacjami, które warto nazwać wprost.
Pierwsza to przejęty serwer headscale. Serwer koordynacyjny przechowuje politykę i decyduje, które węzły się poznają. Kto ma roota na tym serwerze, może zmienić politykę, dodać własny węzeł albo nadać mu dowolny tag. Szerzej piszemy o tym w tekście o tym, co serwer koordynacyjny Tailscale może, a czego nie może. Przy headscale tym serwerem jesteś Ty. Chroń go jak każdy serwer z dostępem administratora.
Druga to przejęty klucz węzła. Ktoś, kto ukradnie klucz z laptopa Bartka, jest dla sieci Bartkiem. Dostaje dokładnie to, co dają mu granty, czyli port 5432 na bazie. Dobra polityka ogranicza szkody, ale ich nie usuwa. Gdy laptop zginie, od razu usuń jego węzeł z headscale. Jak tunel WireGuard pod spodem wiąże klucze z adresami, wyjaśnia tekst o routingu opartym na kluczach w WireGuard.
Zła zmiana może też odciąć Ciebie. Jeden brakujący grant albo pusta lista grants blokuje SSH przez sieć tailnet. Na czas testów miej drogę do serwera, która nie przechodzi przez tailnet: konsolę u dostawcy VPS albo publiczny port SSH chroniony kluczem i firewallem. Zamknij ją dopiero wtedy, gdy nowa polityka działa, a testy przechodzą.
FAQ
Dlaczego po dodaniu pierwszego grantu w headscale nic nie działa?
Grants działają według zasady: wszystko jest zabronione, chyba że grant na coś pozwala. Dopóki plik nie ma acls ani grants, headscale przepuszcza cały ruch. Pierwszy grant zamyka wszystko, czego nie wymienia, także ruch między urządzeniami tego samego użytkownika. Dodaj grant z "src": ["autogroup:member"], "dst": ["autogroup:self"] i "ip": ["*"], a dla administratorów osobny grant do serwerów z tagami.
Zmieniłem plik polityki, ale headscale dalej stosuje stare reguły. Co jest nie tak?
W trybie file headscale czyta plik dopiero po przeładowaniu. Uruchom sudo systemctl reload headscale i przeczytaj sudo journalctl -u headscale -n 20 --no-pager. Headscale zapisuje tam wynik każdego przeładowania, także nieudany test z bloku tests, który odrzuca zmianę. Nie polegaj na headscale policy get, bo w trybie file pokazuje ono treść pliku z dysku, a nie politykę w pamięci serwera.
Dlaczego headscale policy set zwraca błąd?
headscale policy set działa tylko wtedy, gdy policy.mode w config.yaml ma wartość database. W trybie file serwer odpowiada błędem update is disabled for modes other than 'database'. W tym trybie edytuj plik wskazany w policy.path i przeładuj headscale. Tryb database jest potrzebny głównie wtedy, gdy politykę ma zapisywać panel WWW, na przykład Headplane.
Jak zapisać użytkownika w polityce headscale?
Jako nazwę użytkownika headscale ze znakiem @ na końcu i bez domeny, na przykład ania@. Nazwy sprawdzisz poleceniem sudo headscale users list. Nazwa bez @ kończy się błędem username must contain @. W bloku tests pole src to pojedynczy napis, na przykład "bartek@", a nie lista.
Czy mogę skopiować politykę z Tailscale do headscale?
Częściowo. Grupy, tagi, grants, stare acls, reguły SSH i testy działają. Device postures (postures, srcPosture) i IP sets nie działają. Z autogrup headscale 0.29.7 zna tylko internet, member, tagged, self, nonroot i danger-all. Przed wgraniem uruchom sudo headscale policy check -f z nazwą pliku i przeczytaj dziennik po przeładowaniu.