hampusstrom.headscale

Ansible Role: Headscale

Rola Ansible do instalacji i konfiguracji Headscale, otwartoźródłowej, samodzielnie hostowanej implementacji serwera kontrolnego Tailscale.

To jest świetne, sprawdź: juanfont/Headscale

Zastrzeżenie

Autor tego projektu nie jest w żaden sposób związany z projektem headscale ani z firmą Tailscale Inc.

OPROGRAMOWANIE JEST DOSTARCZANE "TAK JAK JEST", BEZ ŻADNEJ GWARANCJI, JAWNEJ ANI IMPLICITNEJ, W TYM, ALE NIE OGRANICZAJĄC SIĘ DO GWARANCJI ZDATNOŚCI HANDLOWEJ, PRZYDATNOŚCI DO OKREŚLONYCH CELÓW ORAZ BRAKU NARUSZEŃ. W ŻADNYM WYPADKU AUTOR NIE PONOSI ODPOWIEDZIALNOŚCI ZA ŻADNE ROSZCZENIA, SZKODY LUB INNE OBOWIĄZKI, CZY TO W RAMACH UMOWY, DELIKTU CZY INACZEJ, WYNIKAJĄCE Z LUB ZWIĄZANE Z OPROGRAMOWANIEM LUB UŻYTKOWANIEM LUB INNYMI TRANSAKCJAMI ZWIĄZANYMI Z OPROGRAMOWANIEM.

KORZYSTASZ NA WŁASNĄ ODPOWIEDZIALNOŚĆ

Kompatybilność

Ta rola była testowana na następujących platformach:

CentOS 8 x64
Debian 10 x64
Debian 11 x64
Ubuntu Server 20.04 x64
Ubuntu Server 22.04 x64

Instalacja

ansible-galaxy

ansible-galaxy install hampusstrom.headscale

Instalacja ręczna

Tylko dla bieżącego użytkownika:

git clone https://github.com/hampusstrom/ansible-role-headscale.git ~/.ansible/roles/hampusstrom.headscale

Globalnie dla systemu:

git clone https://github.com/hampusstrom/ansible-role-headscale.git /etc/ansible/roles/hampusstrom.headscale

Wymagania

Ta rola nie ma szczególnych wymagań i powinna działać wszędzie tam, gdzie działa Ansible, Headscale i systemd.

GitHub API

Ta rola korzysta z API GitHub.

API GitHub ma limity.

Nieautoryzowani użytkownicy mogą wykonywać tylko 60 zapytań na godzinę.

Jeśli jesteś deweloperem, może to być łatwe do przekroczenia.

Aby to obejść, możesz uzyskać Token dostępu osobistego na: https://github.com/settings/tokens/new

Wypełnij szczegóły tokenu dostępu w zmiennych headscale_github_api_*.

headscale_github_api_username: twoja_nazwa_użytkownika_github

headscale_github_api_password: twój_token_dostępu_osobistego

headscale_github_api_auth: true

System(y) inicjalizacyjne: systemd

Wymagane uprawnienia roota: tak

Ponieważ wymagamy roota, użyj tej roli w playbooku, który ma globalnie zdefiniowane become:yes lub wywołaj tę rolę za pomocą słowa kluczowego become: yes.

- hosts: headscale
  become: yes
  roles:
    - role: hampusstrom.headscale

# LUB

- hosts: headscale
  roles:
    - role: hampusstrom.headscale
      become: yes

Zmienne roli

Pełny opis wszystkich dostępnych zmiennych można znaleźć w defaults/main.yaml.

Konwencja nazewnictwa zmiennych

Zmienne związane z tą rolą zawsze mają prefiks headscale_.

headscale_version

Definiuje wersję headscale do pobrania i zainstalowania na docelowych maszynach. Może być to numer wersji (bez prefiksu 'v'). Tj. 0.16.4 lub latest

"latest" automatycznie pobierze najnowszy tag wydania z repozytorium juanfont/headscale.

domyślnie: latest

headscale_config

Zawartość pliku konfiguracyjnego headscale config.yaml wyrażona jako obiekt yaml. Sprawdź domyślną konfigurację w projekcie headscale dla inspiracji. W momencie pisania wymagane są następujące minimalne wartości dla wersji 0.20.0 headscale.

headscale_config:
  server_url: "http://127.0.01:8080"
  listen_addr: 127.0.0.1:8080
  private_key_path: "{{ headscale_lib_dir_path }}/private.key"
  db_type: sqlite3
  unix_socket: "{{ headscale_run_dir_path }}/headscale.sock"
  ip_prefixes:
    - 100.64.0.0/10
  noise:
    private_key_path: "{{ headscale_lib_dir_path }}/noise_private.key"

headscale_acl

Zawartość pliku headscale acl.yaml wyrażona jako obiekt yaml.

headscale_github_repository

Definiuje użytkownika/repo do użycia przy wyszukiwaniu i pobieraniu binariów headscale. Może być zmienione na inne repozytorium, aby umożliwić instalacje forków, na przykład.

domyślnie: juanfont/headscale

headscale_remove_unmanaged_users

Jeśli ustawione na true, wszyscy użytkownicy niepodani w headscale_users zostaną na stałe usunięci.

Używasz na własną odpowiedzialność

domyślnie: false

headscale_users

Lista użytkowników, którzy powinni być utworzeni i nie usunięci, jeśli używane razem z headscale_remove_unmanaged_users.

domyślnie: []

headscale_binary_path

Definiuje, gdzie binaria headscale zostaną pobrane i zainstalowane.

domyślnie: /usr/local/bin/headscale

headscale_user_name

Definiuje nazwę użytkownika systemowego, który powinien uruchomić demona headscale systemd. Zostanie utworzony, jeśli jeszcze nie istnieje.

domyślnie: headscale

headscale_user_group

Definiuje nazwę głównej grupy dla użytkownika headscale_user_name.

domyślnie: {{ headscale_user_name }}

headscale_user_uid

Definiuje identyfikator użytkownika użytkownika headscale_user_name.

domyślnie: 777

headscale_user_gid

Definiuje identyfikator grupy dla grupy headscale_user_group.

domyślnie: {{ headscale_user_uid }}

headscale_etc_dir_path

Definiuje ścieżkę, w której powinny znajdować się dane konfiguracyjne headscale. Normalnie nie powinno się tego zmieniać, ale dla pewnych niestandardowych konfiguracji/forków opcja jest dostępna.

domyślnie: /etc/headscale

headscale_lib_dir_path

Definiuje ścieżkę, w której powinny znajdować się dane biblioteczne headscale. Normalnie nie powinno się tego zmieniać, ale dla pewnych niestandardowych konfiguracji/forków opcja jest dostępna.

domyślnie: /var/lib/headscale

headscale_run_dir_path

Definiuje ścieżkę, w której powinien znajdować się socket UNIX headscale. Normalnie nie powinno się tego zmieniać, ale dla pewnych niestandardowych konfiguracji/forków opcja jest dostępna. Wpis konfiguracyjny unix_socket powinien wskazywać na plik .sock w tym katalogu. Tj. unix_socket: /var/run/headscale/headscale.sock

domyślnie: /var/run/headscale

headscale_db_path

Ścieżka do pliku bazy danych sqlite.

domyślnie: {{ headscale_lib_dir_path }}/db.sqlite

headscale_backup_dir_path

Ścieżka, w której będą przechowywane kopie zapasowe bazy danych. Kopie zapasowe są automatycznie tworzone przed każdą aktualizacją headscale. Jeśli zdecydujesz się na downgradowanie headscale, zdecydowanie zaleca się również przywrócenie bazy danych. Aby to zrobić, po prostu zatrzymaj headscale, skopiuj plik db do headscale_db_path i uruchom ponownie headscale.

domyślnie: {{ headscale_lib_dir_path }}/backups

Przykładowy Playbook

Zauważ, że zawsze powinieneś sprawdzić oficjalną dokumentację headscale, aby upewnić się, że masz wszystkie wymagane wartości dla swojej wersji headscale. Zdecydowanie polecam skopiowanie oficjalnego przykładu konfiguracji i użycie go jako bazy dla swojej konfiguracji.

---
---
# Uruchom za pomocą polecenia:
# ansible-playbook -i "twojplikzustawien" -K example-playbook.yml
- hosts: all
  become: yes
  vars:
    headscale_version: 0.20.0
    headscale_config:
    # headscale będzie szukać pliku konfiguracyjnego o nazwie `config.yaml` (lub `config.json`) w następującej kolejności:
    #
    # - `/etc/headscale`
    # - `~/.headscale`
    # - bieżący katalog roboczy

    # URL, do którego podłączą się klienci.
    # Zazwyczaj będzie to domena, jak:
    #
    # https://myheadscale.example.com:443
    #
    server_url: http://127.0.0.1:8080

    # Adres do nasłuchu / związania na serwerze
    #
    # Dla produkcji:
    # listen_addr: 0.0.0.0:8080
    listen_addr: 127.0.0.1:8080

    # Adres do nasłuchu dla /metrics, chcesz może
    # utrzymać ten punkt końcowy prywatnym w swojej sieci
    #
    metrics_listen_addr: 127.0.0.1:9090

    # Adres do nasłuchu dla gRPC.
    # gRPC jest używane do kontrolowania serwera headscale
    # zdalnie za pomocą CLI
    # Uwaga: Zdalny dostęp działa _tylko_, jeśli masz
    # ważne certyfikaty.
    #
    # Dla produkcji:
    # grpc_listen_addr: 0.0.0.0:50443
    grpc_listen_addr: 127.0.0.1:50443

    # Zezwala na uruchomienie zdalnego interfejsu gRPC w trybie INSECURE
    # To nie jest zalecane, ponieważ ruch będzie
    # niezaszyfrowany. Włącz to tylko, jeśli wiesz, co robisz.
    grpc_allow_insecure: false

    # Klucz prywatny używany do szyfrowania ruchu między headscale
    # a klientami Tailscale.
    # Plik klucza prywatnego zostanie automatycznie wygenerowany, jeśli będzie brakować.
    #
    # Dla produkcji:
    # /var/lib/headscale/private.key
    private_key_path: ./private.key

    # Sekcja Noise zawiera specyficzną konfigurację dla
    # protokołu Noise TS2021
    noise:
      # Klucz prywatny Noise jest używany do szyfrowania
      # ruchu między headscale a klientami Tailscale, gdy
      # używany jest nowy protokół oparty na Noise. Musi być inny
      # niż starszy klucz prywatny.
      #
      # Dla produkcji:
      # private_key_path: /var/lib/headscale/noise_private.key
      private_key_path: ./noise_private.key

    # Lista prefiksów IP do przydzielania adresów tail.
    # Każdy prefiks składa się z adresu IPv4 lub IPv6,
    # i odpowiadającej długości prefiksu, oddzielonej znakiem ukośnika.
    # Chociaż wygląda na to, że może przyjmować dowolne wartości, musi
    # znajdować się w zakresach IP wspieranych przez klienta Tailscale.
    # IPv6: https://github.com/tailscale/tailscale/blob/22ebb25e833264f58d7c3f534a8b166894a89536/net/tsaddr/tsaddr.go#LL81C52-L81C71
    # IPv4: https://github.com/tailscale/tailscale/blob/22ebb25e833264f58d7c3f534a8b166894a89536/net/tsaddr/tsaddr.go#L33
    ip_prefixes:
      - fd7a:115c:a1e0::/48
      - 100.64.0.0/10

    # DERP to system relay, z którego korzysta Tailscale, gdy nie można nawiązać bezpośredniego
    # połączenia.
    # https://tailscale.com/blog/how-tailscale-works/#encrypted-tcp-relays-derp
    #
    # headscale potrzebuje listy serwerów DERP, które mogą być przedstawione
    # klientom.
    derp:
      server:
        # Jeśli włączone, działa wbudowany serwer DERP i łączy się z resztą konfiguracji DERP
        # Adres URL serwera Headscale zdefiniowany powyżej MUSI używać https, DERP wymaga, aby TLS był aktywowany
        enabled: false

        # ID regionu do użycia dla wbudowanego serwera DERP.
        # Lokalny DERP przeważa, jeśli ID regionu koliduje z innymi ID regionów pochodzącymi z
        # zwykłej konfiguracji DERP.
        region_id: 999

        # Kod regionu i nazwa wyświetlane są w GUI Tailscale, aby zidentyfikować region DERP
        region_code: "headscale"
        region_name: "Headscale Embedded DERP"

        # Nasłuchuje na UDP na skonfigurowanym adresie dla połączeń STUN - pomagając przy NAT traversalu.
        # Gdy lokalny serwer DERP jest włączony, stun_listen_addr MUSI być zdefiniowany.
        #
        # Aby uzyskać więcej informacji na temat tego, jak to działa, zapoznaj się z tym świetnym artykułem: https://tailscale.com/blog/how-tailscale-works/
        stun_listen_addr: "0.0.0.0:3478"

      # Lista zewnętrznych map DERP, zakodowanych w formacie JSON
      urls:
        - https://controlplane.tailscale.com/derpmap/default

      # Lokalne dostępne pliki map DERP zakodowane w formacie YAML
      #
      # Ta opcja jest głównie interesująca dla osób, które hostują
      # własne serwery DERP:
      # https://tailscale.com/kb/1118/custom-derp-servers/
      #
      # paths:
      #   - /etc/headscale/derp-example.yaml
      paths: []

      # Jeśli włączone, zostanie skonfigurowany worker, aby okresowo
      # aktualizować podane źródła i zaktualizować mapę derp.
      auto_update_enabled: true

      # Jak często powinniśmy sprawdzać aktualizacje DERP?
      update_frequency: 24h

    # Wyłącza automatyczne sprawdzanie aktualizacji headscale przy uruchamianiu
    disable_check_updates: false

    # Czas przed usunięciem nieaktywnych ephemerycznych węzłów?
    ephemeral_node_inactivity_timeout: 30m

    # Okres, w którym sprawdzamy aktualizacje węzłów w sieci tailnet. Zbyt niska wartość poważnie wpłynie na
    # zużycie CPU przez Headscale. Zbyt wysoka wartość (powyżej 60s) spowoduje problemy
    # z węzłami, ponieważ nie otrzymają one wystarczająco często aktualizacji ani wiadomości "keep alive".
    # W przypadku wątpliwości nie zmieniaj domyślnej wartości 10s.
    node_update_check_interval: 10s

    # Konfiguracja SQLite
    db_type: sqlite3

    # Dla produkcji:
    # db_path: /var/lib/headscale/db.sqlite
    db_path: ./db.sqlite

    # # Konfiguracja Postgres
    # Jeśli używasz gniazda Unix do połączenia z Postgres, ustaw ścieżkę gniazda w polu 'host' i pozostaw 'port' pusty.
    # db_type: postgres
    # db_host: localhost
    # db_port: 5432
    # db_name: headscale
    # db_user: foo
    # db_pass: bar

    # Jeśli potrzebny jest inny 'sslmode' zamiast 'require(true)' i 'disabled(false)', ustaw 'sslmode', którego potrzebujesz
    # w polu 'db_ssl'. Odnosi się do https://www.postgresql.org/docs/current/libpq-ssl.html Tabela 34.1.
    # db_ssl: false

    ### Konfiguracja TLS
    #
    ## Let's encrypt / ACME
    #
    # headscale wspiera automatyczne żądanie i konfigurację
    # TLS dla domeny za pomocą Let's Encrypt.
    #
    # URL do katalogu ACME
    acme_url: https://acme-v02.api.letsencrypt.org/directory

    # E-mail do rejestracji u dostawcy ACME
    acme_email: ""

    # Nazwa domeny do żądania certyfikatu TLS:
    tls_letsencrypt_hostname: ""

    # Ścieżka do przechowywania certyfikatów i metadanych wymaganych przez
    # letsencrypt
    # Dla produkcji:
    # tls_letsencrypt_cache_dir: /var/lib/headscale/cache
    tls_letsencrypt_cache_dir: ./cache

    # Typ wyzwania ACME do użycia, obecnie obsługiwane typy:
    # HTTP-01 lub TLS-ALPN-01
    # Zobacz [docs/tls.md](docs/tls.md) dla uzyskania dalszych informacji
    tls_letsencrypt_challenge_type: HTTP-01
    # Gdy wyzwanie HTTP-01 jest wybierane, letsencrypt musi skonfigurować
    # punkt końcowy do weryfikacji, który będzie nasłuchiwać na:
    # :http = port 80
    tls_letsencrypt_listen: ":http"

    ## Użyj już zdefiniowanych certyfikatów:
    tls_cert_path: ""
    tls_key_path: ""

    log:
      # Format wyjściowy dla logów: tekst lub json
      format: text
      level: info

    # Ścieżka do pliku zawierającego polityki ACL.
    # ACL mogą być definiowane w formacie YAML lub HUJSON.
    # https://tailscale.com/kb/1018/acls/
    acl_policy_path: ""

    ## DNS
    #
    # headscale wspiera konfigurację DNS Tailscale oraz MagicDNS.
    # Zapoznaj się z ich KB, aby lepiej zrozumieć pojęcia:
    #
    # - https://tailscale.com/kb/1054/dns/
    # - https://tailscale.com/kb/1081/magicdns/
    # - https://tailscale.com/blog/2021-09-private-dns-with-magicdns/
    #
    dns_config:
      # Czy preferować użycie DNS dostarczonego przez Headscale czy lokalnego.
      override_local_dns: true

      # Lista serwerów DNS, które będą udostępniane klientom.
      nameservers:
        - 1.1.1.1

      # NextDNS (zobacz https://tailscale.com/kb/1218/nextdns/).
      # "abc123" to przykładowy ID NextDNS, zastąp swoim.
      #
      # Przy udostępnianiu metadanych:
      # nameservers:
      #   - https://dns.nextdns.io/abc123
      #
      # Bez udostępniania metadanych:
      # nameservers:
      #   - 2a07:a8c0::ab:c123
      #   - 2a07:a8c1::ab:c123

      # Split DNS (zobacz https://tailscale.com/kb/1054/dns/),
      # lista domen wyszukiwawczych i DNS do zapytania dla każdej z nich.
      #
      # restricted_nameservers:
      #   foo.bar.com:
      #     - 1.1.1.1
      #   darp.headscale.net:
      #     - 1.1.1.1
      #     - 8.8.8.8

      # Domena wyszukiwania do wstrzyknięcia.
      domains: []

      # Dodatkowe rekordy DNS
      # jak na razie tylko rekordy A są obsługiwane (po stronie tailscale)
      # Zobacz https://github.com/juanfont/headscale/blob/main/docs/dns-records.md#Limitations
      # extra_records:
      #   - name: "grafana.myvpn.example.com"
      #     type: "A"
      #     value: "100.64.0.3"
      #
      #   # możesz też wpisać to w jednej linii
      #   - { name: "prometheus.myvpn.example.com", type: "A", value: "100.64.0.3" }

      # Czy używać [MagicDNS](https://tailscale.com/kb/1081/magicdns/).
      # Działa tylko, jeśli istnieje co najmniej jeden zdefiniowany serwer nazw.
      magic_dns: true

      # Definiuje podstawową domenę do tworzenia nazw hostów dla MagicDNS.
      # `base_domain` musi być pełną nazwą FQDN, bez kropki na końcu.
      # FQDN hostów będzie mieć postać
      # `hostname.user.base_domain` (np. _myhost.myuser.example.com_).
      base_domain: example.com

    # Gniazdo Unix używane przez CLI do połączenia bez uwierzytelniania
    # Uwaga: do produkcji będziesz chciał ustawić to czegoś jak:
    # unix_socket: /var/run/headscale.sock
    unix_socket: ./headscale.sock
    unix_socket_permission: "0770"
    #
    # headscale wspiera eksperymentalne wsparcie OpenID connect,
    # jest nadal testowane i mogą wystąpić w nim błędy, prosimy
    # o pomoc w testowaniu.
    # OpenID Connect
    # oidc:
    #   only_start_if_oidc_is_available: true
    #   issuer: "https://your-oidc.issuer.com/path"
    #   client_id: "your-oidc-client-id"
    #   client_secret: "your-oidc-client-secret"
    #   # Alternatywnie, ustaw `client_secret_path`, aby odczytać sekret z pliku.
    #   # Umożliwia to rozwiązanie zmiennych środowiskowych, co ułatwia integrację z systemd
    #   # `LoadCredential`:
    #   client_secret_path: "${CREDENTIALS_DIRECTORY}/oidc_client_secret"
    #   # 'client_secret' i 'client_secret_path' są wzajemnie wykluczające się.
    #
    #   # Czas, przez jaki węzeł jest uwierzytelniany za pomocą OpenID, zanim
    #   # wygaśnie i będzie musiał przeprowadzić ponowną autoryzację.
    #   # Ustawiając wartość na "0", oznacza to brak wygaśnięcia.
    #   expiry: 180d
    #
    #   # Użyj terminu wygaśnięcia z tokena uzyskanego z OpenID przy logowaniu użytkownika,
    #   # co zazwyczaj prowadzi do częstej potrzeby ponownej autoryzacji i powinno
    #   # zostać włączone tylko, jeśli wiesz, co robisz.
    #   # Uwaga: włączenie tego spowoduje zignorowanie 'oidc.expiry'.
    #   use_expiry_from_token: false
    #
    #   # Dostosuj zakresy używane w procesie OIDC, domyślnie to "openid", "profile" i "email" oraz dodaj niestandardowe zapytania
    #   # parametry do zapytania Autoryzacji. Zakresy domyślnie to "openid", "profile" i "email".
    #
    #   scope: ["openid", "profile", "email", "custom"]
    #   extra_params:
    #     domain_hint: example.com
    #
    #   # Lista dozwolonych domen głównych i/lub użytkowników. Jeśli domena użytkownika
    #   # autoryzowanego użytkownika nie znajduje się na tej liście, prośba o autoryzację zostanie odrzucona.
    #
    #   allowed_domains:
    #     - example.com
    #   # Uwaga: Grupy z keycloak mają '/' na początku
    #   allowed_groups:
    #     - /headscale
    #   allowed_users:
    #     - [email protected]
    #
    #   # Jeśli 'strip_email_domain' jest ustawione na 'true', część domenowa adresu e-mail użytkownika zostanie usunięta.
    #   # To przekształca `[email protected]` na użytkownika `first-name.last-name`
    #   # Jeśli 'strip_email_domain' jest ustawione na 'false', część domenowa NIE zostanie usunięta, co skutkuje
    #   użytkownik: `first-name.last-name.example.com`
    #
    #   strip_email_domain: true

    # Konfiguracja Logtail
    # Logtail to infrastruktura logowania i audytu Tailscale, pozwala panelowi kontrolnemu
    # instruować węzły tailscale do logowania swojej aktywności na zdalnym serwerze.
    logtail:
      # Włącz logtail dla tych klientów headscale.
      # Ponieważ obecnie nie ma wsparcia dla nadpisania serwera logów w headscale, to jest
      # wyłączone domyślnie. Włączenie tego spowoduje, że Twoi klienci będą przesyłać logi do firmy Tailscale Inc.
      enabled: false

    # Włączenie tej opcji powoduje, że urządzenia preferują losowy port dla ruchu WireGuard zamiast
    # domyślnego statycznego portu 41641. Ta opcja jest przeznaczona jako rozwiązanie problemów z niektórymi
    # wadliwymi urządzeniami zaporowymi. Zobacz https://tailscale.com/kb/1181/firewalls/ dla dalszych informacji.
    randomize_client_port: false

  roles:
    - hampusstrom.headscale