headscale v0.29.3

Un'implementazione open source e self-hosted del server di controllo di Tailscale.

Unisciti al nostro server Discord per chattare.

Nota: Seleziona sempre lo stesso tag GitHub della versione rilasciata che utilizzi per assicurarti di avere la configurazione di esempio corretta. Il branch main potrebbe contenere modifiche non ancora rilasciate. La documentazione è disponibile per le versioni stabili e di sviluppo:

• Documentazione per la versione stabile
• Documentazione per la versione di sviluppo

Cos'è Tailscale

Tailscale è una VPN moderna costruita sopra Wireguard. Funziona come una rete overlay tra i computer delle tue reti - utilizzando il NAT traversal.

Tutto in Tailscale è Open Source, ad eccezione dei client GUI per sistemi operativi proprietari (Windows e macOS/iOS) e del server di controllo.

Il server di controllo funziona come punto di scambio delle chiavi pubbliche Wireguard per i nodi nella rete Tailscale. Assegna gli indirizzi IP dei client, crea i confini tra ciascun utente, abilita la condivisione di macchine tra utenti ed espone le route annunciate dai tuoi nodi.

Una rete Tailscale (tailnet) è una rete privata che Tailscale assegna a un utente in termini di utenti privati o di un'organizzazione.

Obiettivo di progettazione

Headscale mira a implementare un'alternativa self-hosted e open source al server di controllo Tailscale. L'obiettivo di Headscale è fornire a self-hoster e appassionati un server open source che possano usare per i propri progetti e laboratori. Implementa uno scope ristretto, una singola rete Tailscale (tailnet), adatta per un uso personale o per una piccola organizzazione open source.

Sostenere Headscale

Se ti piace headscale e lo trovi utile, nel repository sono disponibili pulsanti per sponsorizzazioni e donazioni.

Funzionalità

Consulta "Features" nella documentazione.

Supporto dei sistemi operativi client

Consulta "Client and operating system support" nella documentazione.

Eseguire headscale

Tieni presente che non supportiamo né incoraggiamo l'uso di reverse proxy e container per eseguire Headscale.

Dai un'occhiata alla documentation.

Per gli utenti NixOS, è disponibile un modulo in nix/.

Build da main

Le build di sviluppo dal branch main sono disponibili come immagini container e binari. Consulta la documentazione sulle build di sviluppo per i dettagli.

Interventi

• Fosdem 2026 (video): Headscale & Tailscale: The complementary open source clone
  • presentato da Kristoffer Dalby
• Fosdem 2023 (video): Headscale: How we are using integration testing to reimplement Tailscale
  • presentato da Juan Font Alonso e Kristoffer Dalby

Disclaimer

Questo progetto non è associato a Tailscale Inc.

Tuttavia, uno dei maintainer attivi di Headscale è impiegato da Tailscale e gli è consentito dedicare ore di lavoro al progetto. I contributi di questo maintainer sono revisionati dagli altri maintainer.

I maintainer lavorano insieme per definire la direzione del progetto. Il principio di fondo è servire la comunità di self-hoster, appassionati e hobbisti - mantenendo al contempo un progetto sostenibile.

Contribuire

Leggi il file CONTRIBUTING.md.

Dai anche un'occhiata al nostro AI_POLICY.md.

Requisiti

Per contribuire a headscale sarebbe necessaria la versione più recente di Go e Buf (generatore Protobuf).

Consigliamo di utilizzare Nix per configurare un ambiente di sviluppo. Questo può essere fatto con nix develop, che installerà gli strumenti e ti fornirà una shell. Ciò garantisce che avrai lo stesso ambiente di sviluppo dei manutentori di headscale.

Stile del codice

Per garantire una certa coerenza con il numero crescente di contributi, questo progetto ha adottato regole di linting e di stile/formattazione:

Il codice Go viene analizzato con golangci-lint e formattato con i formattatori di golangci-lint (gofumpt, gci, goimports). Configura il tuo editor per eseguire gli strumenti durante lo sviluppo e assicurati di eseguire make lint e make fmt prima di effettuare il commit di qualsiasi codice.

Il codice Proto viene analizzato con buf e formattato con clang-format.

La documentazione viene formattata con mdformat.

Il resto (Markdown, YAML, ecc.) viene formattato con prettier.

Dai un'occhiata a .golangci.yaml e Makefile per vedere la configurazione specifica.

Installare gli strumenti di sviluppo

• Go
• Buf
• Strumenti Protobuf

Installa e attiva:

nix develop

Test e build

Alcune parti del progetto richiedono la generazione di codice Go da Protobuf (se vengono apportate modifiche in proto/) e deve essere (ri)generato con:

make generate

Nota: esegui il commit delle modifiche in gen/ separatamente per facilitare la revisione.

Per eseguire i test:

make test

Per compilare il programma:

make build

Flusso di lavoro per lo sviluppo

Consigliamo di utilizzare Nix per la gestione delle dipendenze, per assicurarti di avere tutti gli strumenti necessari. Se preferisci gestire le dipendenze autonomamente, puoi usare direttamente Make:

Con Nix (consigliato):

nix develop
make test
make build

Con le tue dipendenze:

make test
make build

Il Makefile ti avviserà se mancano strumenti richiesti e suggerirà di eseguire nix develop. Esegui make help per vedere tutti i target disponibili.

Contributori

Realizzato con contrib.rocks.