hampusstrom.headscale
Ansible-Rolle: Headscale
Eine Ansible-Rolle zur Installation und Konfiguration von Headscale, einer Open-Source, selbst gehosteten Implementierung des Tailscale- Kontrollservers.
Es ist großartig, schau es dir an: juanfont/Headscale
Haftungsausschluss
Der Autor dieses Projekts ist in keiner Weise mit dem Headscale-Projekt oder Tailscale Inc. verbunden.
DIE SOFTWARE WIRD "WIE BESEHEN" BEREITGESTELLT, OHNE GEWÄHRLEISTUNG JEGLICHER ART, WEDER AUSDRÜCKLICH NOCH IMPLIZIT, EINSCHLIESSLICH, ABER NICHT BESCHRÄNKT AUF GARANTIEN FÜR MARKTFÄHIGKEIT, EIGNUNG FÜR EINEN BESTIMMTEN ZWECK UND KEINEN RECHTSVERSTOSS. IN KEINEM FALL HAFTET DER AUTOR FÜR IRGENDEINE FORDERUNG, SCHÄDEN ODER ANDERE VERPFLICHTUNGEN, ONGELTIG IN EINER KLAGE AUS VERTRAG, DELIKT ODER ANDEREM, DIE AUS, ANLÄSSLICH ODER IN VERBINDUNG MIT DER SOFTWARE ODER DER NUTZUNG ODER ANDEREN HANDLUNGEN IN DER SOFTWARE RESULTIEREN.
NUTZEN SIE AUF EIGENE GEFAHR
Kompatibilität
Diese Rolle wurde auf den folgenden Plattformen getestet:
- CentOS 8 x64
- Debian 10 x64
- Debian 11 x64
- Ubuntu Server 20.04 x64
- Ubuntu Server 22.04 x64
Installation
Ansible-Galaxy
ansible-galaxy install hampusstrom.headscale
Manuelle Installation
Nur für den aktuellen Benutzer:
git clone https://github.com/hampusstrom/ansible-role-headscale.git ~/.ansible/roles/hampusstrom.headscale
Systemweit:
git clone https://github.com/hampusstrom/ansible-role-headscale.git /etc/ansible/roles/hampusstrom.headscale
Anforderungen
Diese Rolle hat keine außergewöhnlichen Anforderungen und sollte überall funktionieren, wo Ansible, Headscale und systemd laufen.
GitHub API
Diese Rolle nutzt die GitHub API.
Die GitHub API ist limitiert.
Unauthentifizierte Benutzer dürfen nur 60 Anfragen pro Stunde stellen.
Wenn Sie ein Entwickler sind, könnten Sie diese Grenze leicht erreichen.
Um dies zu umgehen, können Sie einen persönlichen Zugriffstoken abrufen von: https://github.com/settings/tokens/new
Füllen Sie die Zugriffs-Tokendetails in die Variablen headscale_github_api_* ein.
headscale_github_api_username: ihr_github_login_benutzername
headscale_github_api_password: ihr_persönlicher_zugriffstoken
headscale_github_api_auth: true
Init-System(e): systemd
Root erforderlich: ja
Da wir Root-Rechte benötigen, verwenden Sie diese Rolle in einem Playbook, das become: yes global definiert hat, oder rufen Sie diese Rolle mit dem Schlüsselwort become: yes auf.
- hosts: headscale
become: yes
roles:
- role: hampusstrom.headscale
# ODER
- hosts: headscale
roles:
- role: hampusstrom.headscale
become: yes
Rollenvariablen
Eine vollständige Beschreibung aller verfügbaren Variablen finden Sie in defaults/main.yaml.
Namenskonvention für Variablen
Variablen, die mit dieser Rolle in Verbindung stehen, werden immer mit headscale_ vorangestellt.
headscale_version
Definiert die Version von Headscale, die auf den Zielmaschinen heruntergeladen und installiert werden soll. Kann entweder eine Versionsnummer (ohne 'v'-Präfix) sein. Zum Beispiel 0.16.4 oder latest.
Latest ruft automatisch den neuesten Release-Tag aus dem juanfont/headscale GitHub-Repository ab.
Standard: latest
headscale_config
Der Inhalt der headscale config.yaml-Datei, ausgedrückt als YAML-Objekt. Überprüfen Sie die Standardkonfiguration im Headscale-Projekt zur Inspiration. Zum Zeitpunkt des Schreibens sind die folgenden Mindestwerte für die Version 0.20.0 von Headscale erforderlich.
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
Der Inhalt der headscale acl.yaml-Datei, ausgedrückt als YAML-Objekt.
headscale_github_repository
Definiert den Benutzer/repo, der verwendet werden soll, wenn nach dem Headscale-Binär gesucht und heruntergeladen wird. Kann geändert werden, um Installationen von Forks zu ermöglichen.
Standard: juanfont/headscale
headscale_remove_unmanaged_users
Wenn auf true gesetzt, werden alle Benutzer, die nicht in headscale_users angegeben sind, dauerhaft gelöscht.
Verwendung auf eigene Gefahr
Standard: false
headscale_users
Eine Liste von Benutzern, die erstellt werden sollen und nicht entfernt werden, wenn sie zusammen mit headscale_remove_unmanaged_users verwendet werden.
Standard: []
headscale_binary_path
Definiert, wo die Headscale-Binärdatei heruntergeladen und installiert wird.
Standard: /usr/local/bin/headscale
headscale_user_name
Definiert den Namen des Systembenutzers, der den Headscale systemd-Daemon ausführen soll. Wird erstellt, falls er noch nicht existiert.
Standard: headscale
headscale_user_group
Definiert den Namen der primären Gruppe für den Benutzer headscale_user_name.
Standard: {{ headscale_user_name }}
headscale_user_uid
Definiert die Benutzer-ID des Benutzers headscale_user_name.
Standard: 777
headscale_user_gid
Definiert die Gruppen-ID der Gruppe headscale_user_group.
Standard: {{ headscale_user_uid }}
headscale_etc_dir_path
Definiert den Pfad, in dem die Konfigurationsdaten von Headscale gespeichert werden sollen. Sie sollten dies normalerweise nicht ändern müssen, aber für einige benutzerdefinierte Konfigurationen/Forks ist die Option vorhanden.
Standard: /etc/headscale
headscale_lib_dir_path
Definiert den Pfad, in dem die Bibliotheksdaten von Headscale gespeichert werden sollen. Sie sollten dies normalerweise nicht ändern müssen, aber für einige benutzerdefinierte Konfigurationen/Forks ist die Option vorhanden.
Standard: /var/lib/headscale
headscale_run_dir_path
Definiert den Pfad, in dem die UNIX-Socket-Datei von Headscale gespeichert werden soll. Sie sollten dies normalerweise nicht ändern müssen, aber für einige benutzerdefinierte Konfigurationen/Forks ist die Option vorhanden. Der unix_socket-Konfigurationseintrag sollte auf eine .sock-Datei in diesem Verzeichnis zeigen. z.B. unix_socket: /var/run/headscale/headscale.sock
Standard: /var/run/headscale
headscale_db_path
Pfad zur SQLite-Datenbankdatei.
Standard: {{ headscale_lib_dir_path }}/db.sqlite
headscale_backup_dir_path
Pfad, in dem Datenbanksicherungen gespeichert werden. Sicherungen werden automatisch vor jedem Upgrade von Headscale erstellt. Wenn Sie Headscale downgraden möchten, wird dringend empfohlen, auch Ihre Datenbank wiederherzustellen. Stoppen Sie dazu einfach Headscale, kopieren Sie die DB-Datei in headscale_db_path und starten Sie Headscale neu.
Standard: {{ headscale_lib_dir_path }}/backups
Beispiel-Playbook
Bitte beachten Sie, dass Sie immer die offizielle Headscale-Dokumentation überprüfen sollten, um sicherzustellen, dass Sie alle erforderlichen Werte für Ihre Version von Headscale ausgefüllt haben. Ich empfehle dringend, Das offizielle Konfigurationsbeispiel zu kopieren und als Grundlage für Ihre Konfiguration zu verwenden.
---
---
# Führen Sie den Befehl aus:
# ansible-playbook- i "ihreInventardatei" -K example-playbook.yml
- hosts: all
become: yes
vars:
headscale_version: 0.20.0
headscale_config:
# Headscale sucht nach einer Konfigurationsdatei mit dem Namen `config.yaml` (oder `config.json`) in der folgenden Reihenfolge:
#
# - `/etc/headscale`
# - `~/.headscale`
# - aktuelles Arbeitsverzeichnis
# Die URL, zu der die Clients sich verbinden.
# Typischerweise ist dies eine Domäne wie:
#
# https://meinheadscale.beispiel.com:443
#
server_url: http://127.0.0.1:8080
# Adresse, auf der der Server hören soll / an die er gebunden werden soll
#
# Für die Produktion:
# listen_addr: 0.0.0.0:8080
listen_addr: 127.0.0.1:8080
# Adresse, die für /metrics gehört, Sie möchten möglicherweise
# diesen Endpunkt privat in Ihrem internen
# Netzwerk halten
#
metrics_listen_addr: 127.0.0.1:9090
# Adresse, die für gRPC zu hören ist.
# gRPC wird verwendet, um einen Headscale-Server
# remote mit der CLI zu steuern
# Hinweis: Der Fernzugriff funktioniert _nur_, wenn Sie
# gültige Zertifikate haben.
#
# Für die Produktion:
# grpc_listen_addr: 0.0.0.0:50443
grpc_listen_addr: 127.0.0.1:50443
# Ermöglichen Sie, dass die gRPC-Administrationsschnittstelle in UNSICHEREM
# Modus läuft. Dies wird nicht empfohlen, da der Datenverkehr
# unverschlüsselt ist. Aktivieren Sie dies nur, wenn Sie wissen, was Sie tun.
grpc_allow_insecure: false
# Privater Schlüssel, der verwendet wird, um den Verkehr zwischen Headscale
# und Tailscale-Clients zu verschlüsseln.
# Die private Schlüsseldatei wird automatisch generiert, wenn sie fehlt.
#
# Für die Produktion:
# /var/lib/headscale/private.key
private_key_path: ./private.key
# Der Noise-Bereich enthält spezifische Konfigurationen für das
# TS2021 Noise-Protokoll
noise:
# Der Noise-Privatschlüssel wird verwendet, um den
# Verkehr zwischen Headscale und Tailscale-Clients zu verschlüsseln, wenn
# das neue Noise-basierte Protokoll verwendet wird. Er muss sich von
# dem alten privaten Schlüssel unterscheiden.
#
# Für die Produktion:
# private_key_path: /var/lib/headscale/noise_private.key
private_key_path: ./noise_private.key
# Liste von IP-Präfixen, um Tail-Adressen zuzuweisen.
# Jedes Präfix besteht aus einer IPv4- oder IPv6-Adresse
# und der zugehörigen Präfixlänge, durch einen Slash getrennt.
# Während dies wie willkürliche Werte aussieht, muss es
# innerhalb der von den Tailscale-Clients unterstützten IP-Bereiche liegen.
# 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 ist ein Relais-System, das Tailscale verwendet, wenn eine direkte
# Verbindung nicht hergestellt werden kann.
# https://tailscale.com/blog/how-tailscale-works/#encrypted-tcp-relays-derp
#
# Headscale benötigt eine Liste von DERP-Servern, die den Clients präsentiert werden können.
derp:
server:
# Wenn aktiviert, läuft der eingebettete DERP-Server und wird in die restliche DERP-Konfiguration integriert.
# Die oben definierte Headscale-Server-URL MUSS HTTPS verwenden, DERP erfordert TLS.
enabled: false
# Region-ID, die für den eingebetteten DERP-Server verwendet wird.
# DERP lokal hat Vorrang, wenn die Region-ID mit einer anderen Region-ID aus
# der regulären DERP-Konfiguration kollidiert.
region_id: 999
# Region-Code und Name werden in der Tailscale-Benutzeroberfläche angezeigt, um eine DERP-Region zu identifizieren.
region_code: "headscale"
region_name: "Headscale Embedded DERP"
# Hört über UDP an der konfigurierten Adresse für STUN-Verbindungen - zur Unterstützung
# beim NAT-Traversal.
# Weitere Details finden Sie in diesem großartigen Artikel: https://tailscale.com/blog/how-tailscale-works/
stun_listen_addr: "0.0.0.0:3478"
# Liste von extern verfügbaren DERP-Maps im JSON-Format
urls:
- https://controlplane.tailscale.com/derpmap/default
# Lokal verfügbare DERP-Map-Dateien im YAML-Format
#
# Diese Option ist vor allem für Personen interessant, die eigene DERP-Server hosten:
# https://tailscale.com/kb/1118/custom-derp-servers/
#
# paths:
# - /etc/headscale/derp-example.yaml
paths: []
# Wenn aktiviert, wird ein Worker eingerichtet, um periodisch
# die angegebenen Quellen zu aktualisieren und die derpmap zu aktualisieren.
auto_update_enabled: true
# Wie oft sollen wir nach DERP-Updates suchen?
update_frequency: 24h
# Deaktiviert die automatische Überprüfung auf Headscale-Updates beim Start
disable_check_updates: false
# Zeit, bevor ein inaktives ephemeres Knoten gelöscht wird?
ephemeral_node_inactivity_timeout: 30m
# Zeitraum zur Überprüfung auf Knotenupdates innerhalb des Tailnet. Ein zu niedriger Wert wirkt sich stark auf
# den CPU-Verbrauch von Headscale aus. Ein zu hoher Wert (über 60 s) kann Probleme verursachen,
# da die Knoten nicht häufig genug Updates oder Keep-Alive-Nachrichten erhalten.
# Im Zweifel nicht am Standardwert von 10s ändern.
node_update_check_interval: 10s
# SQLite-Konfiguration
db_type: sqlite3
# Für die Produktion:
# db_path: /var/lib/headscale/db.sqlite
db_path: ./db.sqlite
# # Postgres-Konfiguration
# Wenn Sie einen Unix-Socket verwenden, um eine Verbindung zu Postgres herzustellen, geben Sie den Socket-Pfad im 'host'-Feld an und lassen Sie 'port' leer.
# db_type: postgres
# db_host: localhost
# db_port: 5432
# db_name: headscale
# db_user: foo
# db_pass: bar
# Wenn ein anderer 'sslmode' erforderlich ist anstelle von 'require(true)' und 'disabled(false)', geben Sie den benötigten 'sslmode'
# im 'db_ssl'-Feld an. Siehe https://www.postgresql.org/docs/current/libpq-ssl.html Tabelle 34.1.
# db_ssl: false
### TLS-Konfiguration
#
## Let's encrypt / ACME
#
# Headscale unterstützt das automatische Anfordern und Einrichten
# von TLS für eine Domäne mit Let's Encrypt.
#
# URL zum ACME-Verzeichnis
acme_url: https://acme-v02.api.letsencrypt.org/directory
# E-Mail zur Registrierung bei ACME-Anbieter
acme_email: ""
# Domänenname, für den ein TLS-Zertifikat angefordert werden soll:
tls_letsencrypt_hostname: ""
# Pfad zum Speichern von Zertifikaten und Metadaten, die von
# Let’s Encrypt benötigt werden
# Für die Produktion:
# tls_letsencrypt_cache_dir: /var/lib/headscale/cache
tls_letsencrypt_cache_dir: ./cache
# Typ der verwendeten ACME-Herausforderung, derzeit unterstützte Typen:
# HTTP-01 oder TLS-ALPN-01
# Siehe [docs/tls.md](docs/tls.md) für weitere Informationen
tls_letsencrypt_challenge_type: HTTP-01
# Wenn die HTTP-01-Herausforderung gewählt wurde, muss Let's Encrypt einen
# Überprüfungsendpunkt einrichten, der auf Folgendem hören wird:
# :http = Port 80
tls_letsencrypt_listen: ":http"
## Verwenden Sie bereits definierte Zertifikate:
tls_cert_path: ""
tls_key_path: ""
log:
# Ausgabeformatierung für Logs: text oder json
format: text
level: info
# Pfad zu einer Datei, die ACL-Richtlinien enthält.
# ACLs können im YAML- oder HUJSON-Format definiert werden.
# https://tailscale.com/kb/1018/acls/
acl_policy_path: ""
## DNS
#
# Headscale unterstützt die Tailscale DNS-Konfiguration und MagicDNS.
# Bitte sehen Sie sich ihre KB an, um die Konzepte besser zu verstehen:
#
# - https://tailscale.com/kb/1054/dns/
# - https://tailscale.com/kb/1081/magicdns/
# - https://tailscale.com/blog/2021-09-private-dns-with-magicdns/
#
dns_config:
# Ob bevorzugt werden soll, Headscale bereitgestellten DNS zu verwenden oder lokalen.
override_local_dns: true
# Liste von DNS-Servern, die den Clients zur Verfügung gestellt werden sollen.
nameservers:
- 1.1.1.1
# NextDNS (siehe https://tailscale.com/kb/1218/nextdns/).
# "abc123" ist eine Beispiel-NextDNS-ID, ersetzen Sie sie durch Ihre.
#
# Mit Metadatenfreigabe:
# nameservers:
# - https://dns.nextdns.io/abc123
#
# Ohne Metadatenfreigabe:
# nameservers:
# - 2a07:a8c0::ab:c123
# - 2a07:a8c1::ab:c123
# Split-DNS (siehe https://tailscale.com/kb/1054/dns/),
# Liste von Suchdomänen und dem DNS, um jede zu abzufragen.
#
# restricted_nameservers:
# foo.bar.com:
# - 1.1.1.1
# darp.headscale.net:
# - 1.1.1.1
# - 8.8.8.8
# Suchdomänen, die eingefügt werden sollen.
domains: []
# Zusätzliche DNS-Einträge
# Bisher werden nur A-Records unterstützt (auf der Tailscale-Seite).
# Siehe https://github.com/juanfont/headscale/blob/main/docs/dns-records.md#Limitations
# extra_records:
# - name: "grafana.meinvpn.beispiel.com"
# type: "A"
# value: "100.64.0.3"
#
# # Sie können es auch in einer Zeile eingeben
# - { name: "prometheus.meinvpn.beispiel.com", type: "A", value: "100.64.0.3" }
# Ob [MagicDNS](https://tailscale.com/kb/1081/magicdns/) verwendet werden soll.
# Funktioniert nur, wenn mindestens ein Nameserver definiert ist.
magic_dns: true
# Definiert die Basisdomäne, um die Hostnamen für MagicDNS zu erstellen.
# `base_domain` muss eine FQDN sein, ohne den abschließenden Punkt.
# Die FQDN der Hosts wird sein
# `hostname.user.base_domain` (z.B. _meinhost.meinbenutzer.beispiel.com_).
base_domain: example.com
# Unix-Socket, der für die CLI verwendet wird, um ohne Authentifizierung zu verbinden.
# Hinweis: Für die Produktion sollten Sie dies auf etwas wie setzen:
# unix_socket: /var/run/headscale.sock
unix_socket: ./headscale.sock
unix_socket_permission: "0770"
#
# Headscale unterstützt experimentelle OpenID-Connect-Unterstützung,
# es wird noch getestet und könnte einige Fehler enthalten, bitte
# helfen Sie uns, es zu testen.
# 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"
# # Alternativ können Sie `client_secret_path` festlegen, um das Secret aus der Datei zu lesen.
# # Es löst Umgebungsvariablen auf, was die Integration in systemd's
# # `LoadCredential` unkompliziert macht:
# client_secret_path: "${CREDENTIALS_DIRECTORY}/oidc_client_secret"
# # client_secret und client_secret_path sind gegenseitig ausschließend.
#
# # Die Zeitspanne, ab der ein Knoten mit OpenID authentifiziert ist, bis er
# # abläuft und sich erneut authentifizieren muss.
# # Den Wert auf "0" zu setzen bedeutet, dass es keine Ablaufzeit gibt.
# expiry: 180d
#
# # Verwenden Sie die Ablaufzeit aus dem Token, das bei der Anmeldung vom OpenID empfangen wurde,
# # dies führt typischerweise zu häufigen Anforderungen zur erneuten Authentifizierung und sollte
# # nur aktiviert werden, wenn Sie wissen, was Sie tun.
# # Hinweis: Wenn Sie dies aktivieren, wird `oidc.expiry` ignoriert.
# use_expiry_from_token: false
#
# # Passen Sie die Scopes an, die im OIDC-Flow verwendet werden, standardmäßig auf "openid", "profile" und "email"
# # und fügen Sie benutzerdefinierte Abfrageparameter zur Autorisierungsanforderung hinzu. Scopes sind standardmäßig "openid", "profile" und "email".
#
# scope: ["openid", "profile", "email", "custom"]
# extra_params:
# domain_hint: beispiel.com
#
# # Liste der erlaubten Principal-Domänen und/oder Benutzer. Wenn die Domäne eines authentifizierten Benutzers nicht in dieser Liste enthalten ist, wird die
# # Authentifizierungsanfrage abgelehnt.
#
# allowed_domains:
# - beispiel.com
# # Hinweis: Gruppen von Keycloak haben ein führendes '/'
# allowed_groups:
# - /headscale
# allowed_users:
# - [email protected]
#
# # Wenn `strip_email_domain` auf `true` gesetzt ist, wird der Domainteil der E-Mail-Adresse des Benutzernamens entfernt.
# # Dies verwandelt `[email protected]` in den Benutzer `vorname.nachname`
# # Wenn `strip_email_domain` auf `false` gesetzt ist, wird der Domainteil NICHT entfernt, was zu folgendem führt:
# # Benutzer: `vorname.nachname.beispiel.com`
#
# strip_email_domain: true
# Logtail-Konfiguration
# Logtail ist die Protokollierungs- und Prüfungsinfrastruktur von Tailscale, sie ermöglicht
# dem Kontrollfeld, Tailscale-Knoten anzuweisen, ihre Aktivitäten an einen Remote-Server zu protokollieren.
logtail:
# Aktivieren Sie Logtail für diese Headscale-Clients.
# Da derzeit keine Unterstützung für das Überschreiben des Protokollservers in Headscale besteht, ist dies
# standardmäßig deaktiviert. Wenn Sie dies aktivieren, sendet Ihr Client Protokolle an Tailscale Inc.
enabled: false
# Wenn Sie diese Option aktivieren, bevorzugen Geräte einen zufälligen Port für WireGuard-Verkehr über den
# standardmäßigen statischen Port 41641. Diese Option ist als Workaround für einige fehlerhafte
# Firewall-Geräte gedacht. Weitere Informationen finden Sie unter https://tailscale.com/kb/1181/firewalls/.
randomize_client_port: false
roles:
- hampusstrom.headscale
Tags
installieren
Eine vollständige Installation und Konfiguration von Headscale und seinen Namespaces.
konfigurieren
Aktualisiert nur die Konfigurationsdatei und/oder die systemd-Einheitendatei.
Benutzer
Konfiguriert nur Namespaces.
Lizenz
MIT Lizenz
Deploys Headscale, An open source, self-hosted implementation of the Tailscale control server.
ansible-galaxy install hampusstrom.headscale