Headscale: Sariling Tailscale Control Server sa VPS

Ano ang headscale

Ang headscale ay isang self-hosted na implementation ng Tailscale control server. Dahil dito, ang machine na nagko-coordinate sa iyong private network ay isang VPS na pagmamay-ari mo. Community project ito at hindi pinapatakbo ng Tailscale Inc. Patuloy na ginagamit ng bawat machine ang opisyal na tailscale client, na itinuturo sa iyong server gamit ang isang flag, --login-server.

Ang control server ang bahaging nakaaalam kung sino ang kabilang sa network. Binibigyan nito ang bawat node ng address mula sa 100.64.0.0/10, ipinapamahagi ang mga public key, at sinasabi sa mga node kung saan nila mahahanap ang isa’t isa. WireGuard pa rin ang mga tunnel at node-to-node ang pagkakabuo ng mga ito. Hindi dumadaan sa headscale box ang traffic sa pagitan ng dalawa mong machine, maliban kung hindi makabuo ng direct path at kailangang gumamit ang mga node ng relay. Kapag ikaw mismo ang nagpatakbo ng coordination role na ito, nagbabago kung sino ang may hawak nito, hindi kung ano ang kaya nitong gawin. Kaya mahalagang maunawaan ang maaabot at hindi maaabot ng control server sa modelong ito bago mo ituring ang paglipat bilang security improvement nang mag-isa.

Ang Headscale ay nagbibigay ng isang tailnet (isang Tailscale network) bawat instance. Inilalarawan ito ng proyekto bilang angkop para sa personal na paggamit o isang maliit na organisasyon. Kung tatlo o apat lang ang machine, mas kaunting software ang kailangang patakbuhin at mas kaunti ang maaaring masira sa simpleng WireGuard VPN sa VPS na pagmamay-ari mo. Sulit ang Headscale kapag ayaw mo nang manu-manong gumawa ng [Peer] block para sa bawat bagong laptop. Kadalasan, gastos ang dahilan kung bakit naghahanap ang mga tao ng ibang opsyon. Kaya basahin muna ang aktuwal na saklaw ng hosted free plan bago ka magpatakbo ng server, dahil karaniwang kasya rito ang ilang personal na machine. Kung lampas ka na sa limitasyong iyon, ikumpara ang kabuuang gastos sa halaga ng paid plans bawat user at bawat tagged resource, dahil walang limitasyon ang user devices samantalang may hiwalay na allowance at singil ang tagged resources. Kung gusto mo ng self-hosted control plane ngunit mas nais mo ang sarili mong client at web interface para pamahalaan ang peers kaysa isang drop-in replacement para sa Tailscale, ang NetBird sa iisang VPS ang alternatibong dapat mong isaalang-alang. Parehong ipinapadaan ng mga ito ang traffic sa WireGuard. Kaya nakasalalay ang pagpili sa paraan ng pagsulat mo ng access rules at sa pag-uugali ng mga relay. Mainam na ikumpara ang NetBird at Tailscale sa mga puntong ito bago mo i-install ang alinman sa mga ito. Para sa mas malawak na paghahambing ng dalawang modelong ito, tingnan ang pagkakaiba ng WireGuard at Tailscale.

Mga kailangan bago mag-install

• Isang VPS na nagpapatakbo ng Ubuntu 24.04, may public IPv4 address, at may sudo access. Kung bago ang server, sundin muna ang unang sampung minuto sa isang bagong VPS.
• Isang DNS A record na nakaturo sa address na iyon. Ginagamit ng gabay na ito ang headscale.example.com.
• Isang hiwalay na domain o subdomain para sa MagicDNS. Ginagamit ng gabay na ito ang tailnet.example.net. Hindi ito dapat kapareho ng domain sa server_url.
• Isang client machine na sasali, na nagpapatakbo ng Linux, macOS, Windows, Android, o iOS. Nangangailangan ang Headscale 0.29.6 ng Tailscale client version 1.80.0 o mas bago.

I-install ang headscale mula sa opisyal na .deb

Naglalabas ang proyekto ng mga .deb package sa GitHub releases page nito. Noong October 27, 2026, ang pinakabagong stable release ay 0.29.6, na inilabas noong October 24, 2026. Suriin muna ang architecture mo dahil kasama ito sa file name.

sudo apt update
sudo apt install -y wget
dpkg --print-architecture

Nagpi-print ito ng amd64 sa karaniwang x86 VPS at arm64 sa Ampere o Graviton style plan. Ilagay ang sagot sa variable sa ibaba.

HEADSCALE_VERSION="0.29.6"
HEADSCALE_ARCH="amd64"
wget --output-document=headscale.deb \\
  "https://github.com/juanfont/headscale/releases/download/v${HEADSCALE_VERSION}/headscale_${HEADSCALE_VERSION}_linux_${HEADSCALE_ARCH}.deb"
sudo apt install -y ./headscale.deb
headscale version

Kailangan ang ./ sa unahan ng file name. Kung wala ito, hahanapin ng apt ang package na tinatawag na headscale.deb sa repositories mo at mabibigo.

Gumagawa ang package ng headscale system user, nagsusulat ng default na /etc/headscale/config.yaml, nag-i-install ng systemd unit, at pagkatapos ay sinisimulan ang service. Kaya tumatakbo na ang headscale kapag nagbalik ang apt, at nagpi-print ang sudo systemctl is-active headscale ng active. Sa bagong install, hindi ino-enable ng package ang unit. Hindi babalik ang service pagkatapos ng reboot hangga't hindi mo ito ine-enable, at ginagawa ito ng restart step sa ibaba. Tumatakbo rin ito gamit ang configuration na kasama sa package. Itinuturo nito ang server_url sa http://127.0.0.1:8080, na hindi address na maaabot ng alinman sa client mo. Wala pang inilalantad dahil loopback din ang listen_addr na kasama sa package. Gayunman, huwag munang mag-join ng client hangga't hindi mo naitatakda ang server_url at nare-restart ang service. Ginagawa ito ng susunod na dalawang step.

I-configure ang server_url bago sumali ang anumang client

I-edit ang /etc/headscale/config.yaml gamit ang sudo nano /etc/headscale/config.yaml, o ilapat ang parehong tatlong pagbabago gamit ang sed. Magtabi ng kopya ng orihinal dahil mahaba at maraming komento ang file. Ito ang pinakamainam mong reference para sa iba pang setting.

sudo cp /etc/headscale/config.yaml /etc/headscale/config.yaml.orig
sudo sed -i 's|^server_url:.*|server_url: https://headscale.example.com|' /etc/headscale/config.yaml
sudo sed -i 's|^listen_addr:.*|listen_addr: 127.0.0.1:8080|' /etc/headscale/config.yaml
sudo sed -i 's|^  base_domain:.*|  base_domain: tailnet.example.net|' /etc/headscale/config.yaml
sudo grep -E '^(server_url|listen_addr):|^  base_domain:' /etc/headscale/config.yaml

Ang server_url ang public address na ginagamit ng headscale sa pagbuo ng mga registration URL. Ginagamit ng mga client ang control address na naka-configure gamit ang --login-server, kaya gamitin ang parehong public name na may https:// sa parehong lugar, at huwag kailanman gamitin ang 127.0.0.1. Ayon sa dokumentasyon ng headscale, posible ang plain HTTP o HTTPS sa port na iba sa 443, pero mariin nitong inirerekomenda ang HTTPS sa port 443 para sa production. Ipinapalagay ito ng natitirang bahagi ng gabay.

Ang listen_addr ang address kung saan nagbi-bind ang proseso. Iwanan ito sa loopback. Ang reverse proxy sa parehong server ang nagte-terminate ng TLS (transport layer security) at nagpapasa ng mga request dito, kaya walang nasa labas ng server ang kailangang makaabot sa port 8080.

Ang base_domain ang MagicDNS suffix, o domain kung saan ibinibigay ang mga pangalan ng iyong node. Dapat itong isang fully qualified domain name na walang trailing dot. Dapat din itong ibang domain kaysa sa nasa server_url dahil kung hindi, magco-collide ang dalawang namespace.

Huwag baguhin ang seksiyon ng database. Ang default ay SQLite sa /var/lib/headscale/db.sqlite, sa directory na ginawa at pagmamay-ari ng package. Sapat na ang SQLite para sa tailnet na ganito kalaki.

I-restart ang headscale at patunayang tumatakbo ito

sudo systemctl restart headscale
sudo systemctl enable headscale
sudo systemctl is-active headscale
sudo systemctl is-enabled headscale
curl -sS -o /dev/null -w '%{http_code}\\n' http://127.0.0.1:8080/health

Ang is-active ay nagpi-print ng active, ang is-enabled ay nagpi-print ng enabled, at ang curl ay nagpi-print ng 200. Ang restart ang hakbang na naglo-load ng mga pagbabago mo. Binabasa ng Headscale ang configuration nang isang beses, kapag nagsisimula ito. Dahil dito, patuloy na ginagamit ng prosesong sinimulan ng package ang inilabas na server_url hanggang sa i-restart mo ito. Hindi ginagawa ng sudo systemctl enable --now headscale ang trabahong ito. Tumatakbo na ang service, kaya walang binabago ang --now start at nananatiling aktibo ang dating value. Ang pagsisimula sa boot ay tungkulin ng enable, at hindi ito awtomatikong ginagawa para sa iyo. Sa bagong install, sinisimulan ng package ang service nang hindi ito ine-enable, kaya patakbuhin ang sudo systemctl enable headscale nang isang beses, gaya sa itaas.

Kung may i-print ang is-active na iba sa active, o hindi nagpi-print ang curl ng 200, basahin ang journal gamit ang sudo journalctl -u headscale -n 50 --no-pager. Halos palaging configuration file ang sanhi ng failure sa yugtong ito. Kailangang i-parse ng headscale ang buong file bago ito magbukas ng socket, kaya pinahihinto ng maling indentation o invalid na required setting ang proseso bago ito makinig sa anumang port. Ayusin ang file, pagkatapos ay sudo systemctl restart headscale. Kailangang gawin ang parehong restart sa bawat susunod na pagbabago sa configuration. Awtomatikong muling kumokonekta ang mga client pagkatapos nito. Kung bago sa iyo ang systemd units, ipinapaliwanag sa pagpapatakbo ng sarili mong services at timer gamit ang systemd ang mga command na ginamit dito.

Suriin ang state files habang nasa shell ka:

stat -c '%U %n' /var/lib/headscale/db.sqlite /var/lib/headscale/noise_private.key

Nagsisimula sa headscale ang dalawang linya. Ito ang unprivileged user na ginawa ng package. Ang noise_private.key ang identity ng server para sa mga client nito. Huwag itong tanggalin. Kapag tinanggal mo ito, gagawa ang headscale ng bago, at kailangang kunin ng mga client ang bagong server key bago muling kumonekta. Mananatili sa database ang mga dati nang registration.

Ilagay ang TLS sa harap ng headscale

Dapat maabot ng mga client ang server_url gamit ang HTTPS. Ang Caddy ang pinakamaikling paraan dahil awtomatiko nitong hinihiling at nire-renew ang certificate.

sudo apt install -y caddy

Palitan ang /etc/caddy/Caddyfile ng block mula sa dokumentasyon ng headscale:

headscale.example.com {
    reverse_proxy 127.0.0.1:8080 {
        header_up True-Client-IP {remote_host}
        header_up X-Real-IP {remote_host}
    }
}

sudo caddy validate --adapter caddyfile --config /etc/caddy/Caddyfile
sudo systemctl restart caddy
sudo systemctl is-active caddy

Ipinapakita ng validate ang adapted config to JSON kapag tama ang parsing ng file. Cosmetic lamang ang warning na hindi naka-format ang file. Mula sa iyong laptop, dapat ipakita rin ng curl -sS -o /dev/null -w '%{http_code}\\n' https://headscale.example.com/health ang 200. Pinatutunayan ng nag-iisang check na iyon na gumagana nang magkakasama ang DNS, firewall, certificate, at proxy.

Narito ang detalye sa proxy na madalas kumakain ng isang gabi sa pag-troubleshoot. Ang Tailscale control connection ay isang HTTP upgrade. Sinisimulan ito gamit ang POST sa halip na GET, at ang value ng Upgrade header ay tailscale-control-protocol. Ipinapasa ito ng Caddy nang walang karagdagang configuration. Hindi ito ginagawa ng nginx, kaya kailangang tahasang ipasa ng nginx front end ang Upgrade at Connection headers. Ginagawa ito ng dokumentasyon ng headscale gamit ang upgrade map:

map $http_upgrade $connection_upgrade {
    default keep-alive;
    ''      close;
}

server {
    listen 443 ssl;
    server_name headscale.example.com;
    location / {
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_buffering off;
        proxy_pass http://127.0.0.1:8080;
    }
}

Kung aalisin mo ang mga linyang iyon, magpapatuloy pa ring gumana ang mga ordinaryong request. Kaya nagbabalik ang /health ng 200 at mukhang maayos ang lahat, pero hindi nabubuo ang control connection: hindi makakapag-register ang mga bagong node, at hindi makakakonekta muli at makakapag-ulat na online ang mga kasalukuyang node. Kung nginx ang gagamitin mo, tinatalakay ng Certbot sa Ubuntu 24.04 gamit ang nginx ang bahagi ng certificate.

Aling mga port ang bubuksan sa UFW

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verbose

Dumadaan sa port 443 ang control connection ng bawat client papunta sa headscale. Kung io-enable mo sa hinaharap ang embedded DERP relay, kailangan din nito ang 3478/udp, na tinalakay sa ibaba. Nandoon ang port 80 para sa ACME (automatic certificate management environment) HTTP challenge at sa redirect papunta sa HTTPS. Makakakuha pa rin ang Caddy ng certificate kahit sarado ang port 80, dahil magagamit nito ang TLS-ALPN challenge sa port 443. Pero kapag bukas ang port 80, available ang dalawang challenge at niri-redirect sa HTTPS ang mga plain http:// request.

Mananatiling sarado ang port 8080. Ang listen_addr ay 127.0.0.1:8080, kaya inaabot ng proxy ang headscale sa pamamagitan ng loopback interface at walang firewall rule na kailangan. Walang ilalantad ang pagbubukas ng 8080 sa UFW, dahil walang nakikinig dito mula sa labas, at wala rin itong pakinabang. Tandaan na karamihan ng provider ay may hiwalay na second firewall sa kanilang control panel, bukod sa UFW. Dahil dito, maaaring bukas ang isang port sa server ngunit sarado pa rin sa edge. Ipinapaliwanag nang mas detalyado ng Mga pangunahing kaalaman sa UFW firewall sa isang VPS ang syntax ng mga rule.

Gumawa ng user at preauth key

sudo headscale users create alice
sudo headscale users list

Client ang headscale command. Kumokonekta ito sa tumatakbong daemon gamit ang unix socket sa /var/run/headscale/headscale.sock, na may mode na 0770 at pagmamay-ari ng headscale group. Dalawang bagay ang resulta nito. Magfa-fail ang command kapag naka-stop ang service. Ito ang isa pang dahilan kung bakit mahalaga ang pagkakasunod-sunod sa gabay na ito. Kailangan din nito ng sudo maliban kung idaragdag mo ang sarili mong account sa headscale group.

Nagpi-print ang users list ng ID sa tabi ng bawat pangalan. Kailangan mo ang numerong iyon dahil numeric user ID ang tinatanggap ng key command, hindi pangalan.

sudo headscale preauthkeys create --user 1 --expiration 24h

Isang beses lang pini-print ang key. Kopyahin ito ngayon. Isang beses lang magagamit ang preauth key at valid ito nang isang oras maliban kung iba ang itatakda mo. Kaya mainam na itakda ang --expiration 24h habang nagte-test ka pa. Idagdag ang --reusable para sa key na mag-e-enroll ng ilang machine. Ituring ito na parang password dahil maaaring sumali sa network mo ang sinumang may hawak nito.

Ikonekta ang unang client gamit ang --login-server

Sa machine na gusto mong isali:

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up --login-server https://headscale.example.com --auth-key 'hskey-auth-PASTE-YOUR-KEY-HERE'
tailscale status
tailscale ip -4

Ipinapakita ng tailscale ip -4 ang address na itinalaga ng headscale, gaya ng 100.64.0.1. Bumalik sa server at ipinapakita ng sudo headscale nodes list ang node kasama ang ID nito, user nito, at online state nito.

Gamitin ang public HTTPS address mula sa server_url para sa --login-server. Tinatanggal ng client ang mga trailing slash sa control URL nito. Walang eksaktong string comparison na nag-aatas na alisin mo ang trailing slash.

Ang machine na dati nang naka-sign in sa hosted service ng Tailscale ay nananatiling naka-sign in doon. Patakbuhin muna ang sudo tailscale logout dito, saka patakbuhin ang tailscale up gamit ang --login-server.

Kung hindi mo ilalagay ang --auth-key, magpi-print ang client ng URL. Buksan ito, at ipapakita ng page ang identifier para sa registration attempt na iyon. I-approve ito sa server:

sudo headscale auth register --user alice --auth-id PASTE-THE-ID-FROM-THE-PAGE

Mas praktikal ang form na ito para sa sarili mong laptop. Mas angkop ang preauth keys para sa mga scripted na proseso dahil walang kailangang taong magbantay. Kapag node na ang VPS mismo, maaari rin nitong dalhin ang internet traffic ng iba mong machine. Ito ang setup ng exit node, ngunit ang kaibahan ay ina-approve mo sa server ang advertised route gamit ang command na headscale, sa halip na sa hosted admin console. Kung ang kailangan mo ay access sa private network sa likod ng VPS, hindi daan palabas sa internet, saklaw din ng parehong approval step ang pag-advertise ng subnet na iyon sa natitirang bahagi ng tailnet. Iba naman ang pag-publish ng isang application mula sa node kaysa sa pag-route ng buong network dito. Ang serve at funnel ang dalawang paraan para gawin ito, ngunit kapwa umaasa ang mga ito sa sariling certificate at ingress machinery ng Tailscale. Ituring ang mga ito bilang mga feature ng hosted tailnet, hindi bilang functionality na ibinibigay ng headscale.

DERP at kung ano ang nagre-relay ng traffic kapag hindi gumana ang direct path

Ang DERP (designated encrypted relay for packets) ang fallback path. Kapag hindi makapagbukas ng direct WireGuard connection ang dalawang node, karaniwan dahil parehong nasa likod ng strict NAT (network address translation), sa halip ay ipinapadala nila ang mga packet sa isang relay. Walang keys ang relay, kaya hindi nito mababasa ang traffic mo. Nakikita nito kung aling mga node ang nag-uusap at kung gaano karaming data ang dumadaan.

Maging malinaw sa ginagawa ng default configuration. Ang Headscale ay naka-configure na tumuro sa https://controlplane.tailscale.com/derpmap/default gamit ang auto_update_enabled: true at update_frequency: 3h, kaya iyo ang control plane habang sa Tailscale naman ang mga relay. Para sa karamihan, makatuwiran ang trade-off na ito. Kung hindi ito katanggap-tanggap, magpatakbo ka ng sarili mong relay.

Para magpatakbo ng sarili mong relay, itakda ang enabled: true sa ilalim ng derp.server sa config.yaml, palitan ang naka-ship na ipv4: 198.51.100.1 at ipv6: 2001:db8::1 ng mga public address ng relay mo, o alisin ang dalawang setting para gumamit ng DNS. Pagkatapos, i-restart ang headscale at buksan ang STUN (session traversal utilities for NAT) port gamit ang sudo ufw allow 3478/udp. Inu-override ng mga address setting na ito ang DNS, kaya kapag naiwan ang alinmang placeholder, magpapadala ito ng mga client sa hindi maaabot na address. Malinaw na nakasaad sa configuration file ang requirement: dapat gumamit ng https ang server_url dahil nangangailangan ang DERP ng TLS. Kapag nilagyan ng laman na walang laman ang derp.urls list, inaalis nito ang mga relay ng Tailscale sa map; tiyaking may gumaganang embedded o custom relay bago ito gawin. Hindi nagsisimula ang Headscale kapag walang laman ang relay map, at kapag relay lang na hindi maaabot ang laman ng map, hindi makakakonekta ang mga node na hindi makapag-direct connect.

Mula sa isang client, ipinapakita ng tailscale netcheck ang latency sa bawat relay region na alam nito, at ipinapakita ng tailscale status ang direct na may address o ang relay na may region code para sa mga aktibong peer connection. Kailangang suriin ang direct path ng peer na naka-stuck sa relay, kasama ang NAT at firewall rules. Ibang isyu naman ang peer na direct pero mabagal pa rin, at ang karaniwang sagot dito ay MTU, hindi ang tunnel mismo.

Bakit offline ang isang node?

Ibinabagsak ng proxy ang upgrade. Ang palatandaan nito ay nagbabalik ng 200 ang /health habang nabibigo ang mga bagong registration o hindi makakonekta muli ang mga kasalukuyang node. Ang control connection ay isang POST na nagdadala ng Upgrade: tailscale-control-protocol, at hinaharangan ng proxy na hindi ito ipinapasa ang registration pati ang channel na nag-uulat ng state ng node. Ihambing ang nginx configuration mo sa mga upgrade line sa itaas, o lumipat sa Caddy upang maalis ang proxy bilang posibleng sanhi.

Nagbago ang public control address. Patuloy na kumokonekta ang mga node sa address na naka-configure gamit ang --login-server; hindi ina-update ng pagpapalit ng server_url ang setting na iyon sa client. Kung hindi na naaabot ng lumang address ang server mo, patakbuhin ang sudo tailscale up --login-server https://headscale.example.com --force-reauth sa bawat node.

Hindi tumatakbo ang client. Sa node, sudo systemctl is-active tailscaled at sudo journalctl -u tailscaled -n 50 --no-pager. Nila-log doon ng client ang mga retry nito kapag hindi nito ma-resolve o maabot ang domain mo.

Nag-expire ang key. Tinalakay ito sa susunod na seksyon.

Para ma-monitor ang server side habang nagsusuri ka, patakbuhin ang sudo journalctl -u headscale -f sa VPS at i-restart ang tailscaled sa client. Suriin din ang client journal: hindi garantiya na ang request na nakakarating sa headscale ay maglalabas ng line sa default log level, kaya hindi sapat ang kawalan ng log sa server upang patunayan na may problema sa DNS, firewall, o proxy.

Pag-expire ng key, at ang node na humihinto makalipas ang ilang linggo

May dalawang magkahiwalay na expiry, at nakapagsasayang ng oras kapag napagpapalit ang mga ito.

Mabilis mag-expire ang preauth keys ayon sa disenyo. Ang default ay isang oras at isang paggamit. Kung tinatanggihan ng tailscale up ang key, gumawa ng panibagong key sa server sa halip na mag-edit ng anuman sa client.

Ang node keys ang pangmatagalang bahagi. Itinatakda ng seksyong node ng config.yaml ang expiry: 0, at nangangahulugan ang 0 na walang default na expiry; maaari pa ring malapat ang tahasang client expiry o OIDC expiry. Exempt ang mga tagged node sa automatic expiry, pero maaaring manual na ipa-expire ng administrator ang mga ito. Itakda ang expiry: 180d kung gusto mo ng 180-araw na default para sa mga non-tagged registration, pero mas mauuna ang expiry na hiningi ng client at maaaring i-override ng OIDC ang default. Hindi retroactive na binabago ng setting na ito ang mga dati nang registration. Kailangang muling mag-authenticate ang node na may expiry bago ang deadline nito gamit ang sudo tailscale up --login-server https://headscale.example.com --force-reauth. Kung walang muling nag-a-authenticate sa isang headless server, mawawala ito sa network kapag nag-expire ang registration nito.

Manu-mano itong gawin kapag may nawalan ng laptop. Ibinibigay sa iyo ng sudo headscale nodes list ang ID, pagkatapos ay nilo-logout ng sudo headscale nodes expire -i 3 ang node na iyon, at tuluyang inaalis ito ng sudo headscale nodes delete -i 3 sa network.

Mga backup at upgrade

Ang /var/lib/headscale at /etc/headscale ang bumubuo sa buong server. Ihinto ang service bago kopyahin ang mga ito, dahil maaaring may kasalukuyang writes ang SQLite at maaaring maging inconsistent ang database kapag kinopya habang may load.

sudo systemctl stop headscale
sudo tar czf /root/headscale-state.tgz -C /var/lib headscale
sudo tar czf /root/headscale-config.tgz -C /etc headscale
sudo systemctl start headscale
sudo chmod 600 /root/headscale-*.tgz

Ilipat ang dalawang file sa labas ng server. Naglalaman ang mga ito ng private keys at lahat ng registration, kaya dapat silang pangasiwaan nang kasing-ingat ng server mismo. Sinasaklaw ng restic backups mula sa isang VPS ang pag-backup nito ayon sa iskedyul at gamit ang encryption.

Umuulit sa proseso ng install ang mga upgrade: i-download ang bagong .deb, sudo apt install ./headscale.deb, pagkatapos ay i-restart at muling patakbuhin ang mga check na is-active at /health. Simula sa 0.29, mahigpit ang upgrade path. Hindi pinapayagan ang paglaktaw sa minor version, at hindi rin pinapayagan ang pag-downgrade sa mas lumang minor version. Mag-upgrade ng isang minor version sa bawat pagkakataon, gumawa ng backup bago ang bawat hakbang, at basahin muna ang release notes ng bersyong iyon, dahil binago ng parehong release ang behavior ng ACL policy at inilipat ang ilang configuration key. Kasama rin sa Version 0.29.6 ang mga security update para sa certificate validation at dependencies, kaya dapat i-install ng mga kasalukuyang 0.29 installation ang patch release na ito.

FAQ

Tumatakbo na ba ang headscale agad matapos kong i-install ang .deb?

Oo. Sinisimulan ng package ang service agad pagkaraang ma-install ito, gamit ang isinamang /etc/headscale/config.yaml, na nakikinig lamang sa loopback at nagse-set ng server_url sa http://127.0.0.1:8080. Sa bagong install, hindi nito ine-enable ang service, kaya hindi ito magsisimula sa boot hangga't hindi mo pinapatakbo ang sudo systemctl enable headscale. Hindi magagamit ng mga client ang isinamang address, kaya i-edit ang server_url, listen_addr, at base_domain, pagkatapos ay patakbuhin ang sudo systemctl restart headscale at kumpirmahin gamit ang sudo systemctl is-active headscale. Dapat itong maging restart: binabasa ng headscale ang file kapag nagsisimula lamang ito, at ang enable --now sa service na tumatakbo na ay ine-enable ito para sa boot pero hindi ito nire-restart, kaya nananatiling aktibo ang mga dating value. Kung mabigo ito matapos ang restart, tinutukoy ng sudo journalctl -u headscale -n 50 --no-pager ang problema. Sa yugtong ito, halos palaging YAML error ito dahil bina-parse ng headscale ang buong file bago ito mag-bind sa isang port.

Kailangan ko pa bang i-install ang karaniwang Tailscale client sa mga machine ko?

Oo. Ang control server lamang ang pinapalitan ng headscale. Ang bawat node ay nagpapatakbo ng official client mula sa Tailscale, at itinuturo mo ito sa iyong server gamit ang sudo tailscale up --login-server https://headscale.example.com. Kasama ang flag na iyon sa standard client, kaya walang kailangang i-patch o i-rebuild.

Dumadaan ba sa headscale server ang traffic ko?

Karaniwan, hindi. Kino-coordinate ng headscale ang network at namamahagi ito ng mga key at address, habang direktang dumadaan sa WireGuard sa pagitan ng mga node ang data path. Dumadaan lamang sa ibang ruta ang traffic kapag hindi direktang maabot ng dalawang node ang isa't isa at gumagamit sila ng DERP relay bilang fallback. Sa isinamang configuration, mga public relay ng Tailscale ang ginagamit. Patakbuhin ang tailscale status sa isang node upang makita kung ang isang partikular na peer ay direct o nasa relay.

Bakit offline pa rin ang node ko matapos itong mag-register?

Ang node na lumilitaw sa headscale nodes list pero hindi kailanman nagiging online ay nangangailangan ng pagsusuri sa control connection nito, kabilang ang reverse proxy. Ang connection na ito ay isang HTTP upgrade na ipinapadala bilang POST na may header na Upgrade: tailscale-control-protocol. Ibinabagsak ito ng nginx maliban kung tahasan mong ipapasa ang Upgrade at Connection headers gamit ang proxy_set_header, na ginagawa ng naunang configuration sa pamamagitan ng map $http_upgrade $connection_upgrade block nito. Pinipigilan din ng pag-drop sa mga header na ito ang pag-register ng mga bagong node. Ipinapasa ito ng Caddy nang walang karagdagang configuration, kaya mabilis itong gamitin upang subukan kung ang proxy ang sanhi ng problema.

Kailangan ko ba ng domain name at TLS para sa headscale?

Oo, para sa setup na ito: gumamit ng domain name at HTTPS. Maaari ring saklawin ng certificates ang mga bare IP address, pero sinasabi sa configuration file na nangangailangan ng TLS ang DERP. Ang domain kasama ang Caddy ay tumatagal ng humigit-kumulang limang minuto at nagbibigay sa iyo ng HTTPS endpoint na awtomatikong nagre-renew. Posible ang plain HTTP, pero mahigpit na inirerekomenda ng documentation ng headscale ang HTTPS sa port 443 para sa production. Binabanggit din nito na ipinapalagay ng Tailscale client ang HTTPS sa port 443 sa ilang sitwasyon.