Headscale: Jisimamie Seva Yako ya Tailscale

Headscale ni nini

Headscale ni utekelezaji unaojisimamia wa seva ya udhibiti ya Tailscale. Hivyo, mashine inayoratibu mtandao wako wa faragha ni VPS unayomiliki. Ni mradi wa jumuiya na hauendeshwi na Tailscale Inc. Kila mashine bado huendesha mteja rasmi wa tailscale, unaoelekezwa kwenye seva yako kwa kutumia flag moja, --login-server.

Seva ya udhibiti ndiyo inayojua ni nani aliye kwenye mtandao. Huipa kila node anwani kutoka 100.64.0.0/10, husambaza funguo za umma, na kuziambia node mahali pa kupatana. Njia za handaki bado ni WireGuard na hujengwa kutoka node moja hadi nyingine. Trafiki kati ya mashine zako mbili haipiti kwenye mashine ya headscale, isipokuwa njia ya moja kwa moja haiwezi kujengwa na node zikatumia relay.

Headscale huhudumia tailnet moja (mtandao mmoja wa Tailscale) kwa kila instance. Mradi unaeleza kuwa hii inafaa kwa matumizi binafsi au shirika dogo. Ukiwa na mashine tatu au nne, VPN ya kawaida ya WireGuard kwenye VPS unayomiliki ina programu chache za kuendesha na vitu vichache vya kuharibika. Headscale huwa na faida wakati hutaki tena kuandika mwenyewe block ya [Peer] kwa kila laptop mpya. Kwa ulinganisho mpana wa miundo hii miwili, soma tofauti kati ya WireGuard na Tailscale.

Unachohitaji kabla ya kusakinisha

• VPS inayoendesha Ubuntu 24.04, yenye anwani ya umma ya IPv4 na ufikiaji wa sudo. Ikiwa server ni mpya, kwanza fuata dakika kumi za kwanza kwenye VPS mpya.
• Rekodi ya DNS A inayoelekeza kwenye anwani hiyo. Mwongozo huu unatumia headscale.example.com.
• Domain au subdomain ya pili kwa MagicDNS. Mwongozo huu unatumia tailnet.example.net. Haipaswi kuwa domain ileile iliyo kwenye server_url.
• Mashine moja ya client ya kujiunga, inayoendesha Linux, macOS, Windows, Android au iOS.

Sakinisha headscale kutoka kwa kifurushi rasmi cha .deb

Mradi hutoa vifurushi vya .deb kwenye ukurasa wake wa matoleo ya GitHub. Kufikia Julai 2026, toleo la sasa ni 0.29.3. Kagua usanifu wako kwanza, kwa sababu jina la faili linaonyesha usanifu huo.

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

Hii huchapisha amd64 kwenye VPS ya kawaida ya x86 na arm64 kwenye mpango wa aina ya Ampere au Graviton. Weka jibu kwenye kigezo kilicho hapa chini.

HEADSCALE_VERSION="0.29.3"
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

./ iliyo mbele ya jina la faili inahitajika. Bila hiyo, apt hutafuta kifurushi kinachoitwa headscale.deb kwenye hazina zako na hushindwa.

Kifurushi huunda mtumiaji wa mfumo wa headscale, huandika /etc/headscale/config.yaml chaguomsingi, na husakinisha kitengo cha systemd. Hakiwashi huduma, na huo ndio mpangilio sahihi. Usanidi unaosafirishwa unaelekeza server_url kwenye http://127.0.0.1:8080, ambayo si anwani ambayo mteja wako yeyote anaweza kufikia. Kwa hiyo, huduma ikiwashwa sasa itakuwa na usanidi usio sahihi hata kama itaanza. Kuendesha sudo systemctl is-active headscale katika hatua hii huchapisha inactive. Hilo linatarajiwa, si hitilafu.

Sanidi server_url kabla ya kuanzisha huduma

Hariri /etc/headscale/config.yaml kwa kutumia sudo nano /etc/headscale/config.yaml, au tumia sed kutekeleza mabadiliko hayo matatu. Hifadhi nakala ya asili, kwa sababu faili ni refu na lina maelezo mengi ya maoni, na ndilo rejeleo bora ulilo nalo kwa mipangilio mingine.

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

server_url ni anwani ambayo headscale huandika katika kila usajili wa mteja. Baada ya hapo, wateja hutumia mfuatano huo kamili kila mara, kwa hiyo lazima iwe jina la umma lenye https:// mwanzoni, kamwe isiwe 127.0.0.1.

listen_addr ni mahali ambapo mchakato husikiliza. Iache kwenye loopback. Reverse proxy iliyo kwenye seva hiyo hiyo hushughulikia TLS (usalama wa safu ya usafirishaji) na kupeleka maombi kwake, kwa hiyo hakuna kitu nje ya seva kinachohitaji kufikia port 8080.

base_domain ni kiambishi cha MagicDNS, yaani domain ambayo nodi zako hupata majina chini yake. Lazima iwe fully qualified domain name isiyo na nukta ya mwisho, na lazima iwe domain tofauti na iliyo katika server_url, kwa sababu nafasi hizo mbili za majina zingegongana vinginevyo.

Acha sehemu ya database bila kuibadilisha. Chaguo-msingi ni SQLite kwenye /var/lib/headscale/db.sqlite, ndani ya saraka iliyoundwa na inayomilikiwa na package, na SQLite inatosha kwa tailnet ya ukubwa huu.

Anzisha headscale na uthibitishe kuwa inaendelea kufanya kazi

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

is-active huchapisha active, na curl huchapisha 200. enable --now hufanya sehemu zote mbili za kazi: huanzisha huduma na kuiweka ianze baada ya kuwasha upya mfumo.

Ikiwa is-active huchapisha failed, soma jarida kwa kutumia sudo journalctl -u headscale -n 50 --no-pager. Kushindwa katika hatua hii karibu kila mara husababishwa na faili ya usanidi, kwa sababu headscale huchanganua faili lote kabla ya kufungua soketi. Kwa hiyo, upachikaji usio sahihi au ufunguo usiojulikana husimamisha mchakato kabla ya huduma yoyote kuanza kusikiliza. Rekebisha faili, kisha sudo systemctl restart headscale. Kila mabadiliko ya baadaye ya usanidi yanahitaji kuwasha upya kwa njia hiyo hiyo. Wateja huunganisha tena wenyewe baadaye. Ikiwa vitengo vya systemd ni vipya kwako, kuendesha huduma na vipima muda vyako kwa kutumia systemd kunaeleza amri zinazotumika hapa.

Kagua faili za hali ukiwa bado kwenye shell:

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

Mistari yote miwili huanza na headscale, mtumiaji asiye na mamlaka ya juu ambaye kifurushi kiliunda. noise_private.key ni utambulisho wa seva kwa wateja wake. Iache. Ukiifuta, headscale itazalisha utambulisho mpya na kila nodi italazimika kujisajili tena.

Weka TLS mbele ya headscale

Wateja lazima wafikie server_url kupitia HTTPS. Caddy ndiyo njia fupi zaidi, kwa sababu huomba na kufanya upya cheti yenyewe.

sudo apt install -y caddy

Badilisha /etc/caddy/Caddyfile kwa kizuizi kutoka kwenye hati za 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

validate huchapisha adapted config to JSON faili inapochanganuliwa bila hitilafu. Onyo kwamba faili haijapangiliwa ni la mwonekano tu. Kutoka kwenye kompyuta yako ya mkononi, curl -sS -o /dev/null -w '%{http_code}\\n' https://headscale.example.com/health inapaswa pia kuchapisha 200. Ukaguzi huo mmoja unathibitisha kuwa DNS, firewall, cheti na proksi zinafanya kazi pamoja.

Haya ndiyo maelezo ya proksi yanayowagharimu watu muda mwingi. Muunganisho wa udhibiti wa Tailscale ni uboreshaji wa HTTP, huanzishwa kwa POST badala ya GET, na thamani ya kichwa cha Upgrade ni tailscale-control-protocol. Caddy hupitisha hilo bila usanidi wa ziada. nginx haifanyi hivyo, kwa hiyo sehemu ya mbele ya nginx inahitaji ramani ya uboreshaji:

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;
    }
}

Ukiacha mistari hiyo, maombi ya kawaida bado yanafanikiwa. Ndiyo maana /health hurudisha 200 na kila kitu huonekana kuwa sawa, huku muunganisho wa udhibiti wa muda mrefu hauanzishwi. Nodi zako husajiliwa kisha hubaki nje ya mtandao. Ukichagua kutumia nginx, Certbot kwenye Ubuntu 24.04 na nginx inaeleza sehemu ya cheti.

Ni milango ipi ifunguliwe katika UFW

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

Mlango 443 hubeba mawasiliano yote ya wateja. Mlango 80 hutumika tu kwa changamoto ya HTTP ya ACME (mazingira ya usimamizi wa vyeti kiotomatiki) na kuelekeza upya kwenda HTTPS. Caddy inauhitaji ili ipate cheti kabisa.

Mlango 8080 hubaki umefungwa. listen_addr ni 127.0.0.1:8080, kwa hiyo proksi hufikia headscale kupitia kiolesura cha loopback na hakuna kanuni ya ngome inayohusika. Kufungua 8080 kwenye intaneti huwapa wateja njia ya udhibiti isiyosimbwa kwa njia fiche na hakutoi faida yoyote. Kumbuka kwamba watoa huduma wengi huendesha ngome ya pili katika paneli yao ya udhibiti, tofauti na UFW. Hivyo, mlango unaweza kuwa wazi kwenye seva lakini bado umefungwa kwenye ukingo wa mtandao. Misingi ya ngome ya UFW kwenye VPS inaeleza sintaksia ya kanuni kwa undani zaidi.

Unda mtumiaji na ufunguo wa preauth

sudo headscale users create alice
sudo headscale users list

Amri ya headscale ni mteja. Huwasiliana na daemon inayoendesha kupitia unix socket iliyo katika /var/run/headscale/headscale.sock. Socket hiyo ina mode 0770 na inamilikiwa na group ya headscale. Hili lina matokeo mawili. Amri hushindwa huduma ikiwa imesimamishwa. Hii ndiyo sababu nyingine ya kuzingatia mpangilio katika mwongozo huu. Pia inahitaji sudo, isipokuwa uongeze akaunti yako kwenye group ya headscale.

users list huchapisha ID karibu na kila jina. Unahitaji nambari hiyo, kwa sababu amri ya key hutumia user ID ya nambari, si jina.

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

Key huchapishwa mara moja tu. Inakili sasa. Preauth key hutumika mara moja na huwa halali kwa saa moja isipokuwa ueleze vinginevyo. Kwa hiyo, ni muhimu kuweka --expiration 24h wakati bado unafanya majaribio. Ongeza --reusable kwa key inayosajili mashine kadhaa. Ichukulie key hiyo kama password, kwa sababu mtu yeyote aliye nayo anaweza kujiunga na network yako.

Unganisha mteja wako wa kwanza kwa kutumia --login-server

Kwenye mashine unayotaka kuunganisha:

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

tailscale ip -4 huchapisha anwani ambayo headscale imegawa, kwa mfano 100.64.0.1. Rudi kwenye seva; sudo headscale nodes list huonyesha nodi pamoja na kitambulisho chake, mtumiaji wake na hali yake ya kuwa mtandaoni.

Thamani ya --login-server lazima ilingane kabisa na server_url, ikijumuisha scheme na bila slash ya mwisho. Thamani hizi hulinganishwa kama mifuatano ya herufi. Kutolingana kunamaanisha kuwa mteja hujisajili kwa anwani moja, kisha huambiwa kuwasiliana na anwani nyingine.

Mashine iliyowahi kuingia katika huduma iliyopangishwa ya Tailscale huhifadhi uingiaji huo. Kwanza endesha sudo tailscale logout kwenye mashine hiyo, kisha endesha tailscale up pamoja na --login-server.

Ukiacha --auth-key, mteja huchapisha URL badala yake. Ifungue; ukurasa utaonyesha kitambulisho cha jaribio hilo la usajili, ambacho unaidhinisha kwenye seva:

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

Njia hiyo ni rahisi zaidi kwa laptop yako mwenyewe. Preauth keys zinafaa zaidi kwa chochote kinachoendeshwa kwa script, kwa sababu hakuna mtu anayehitajika kukifuatilia.

DERP na kile kinachopitisha trafiki njia ya moja kwa moja inaposhindwa

DERP (designated encrypted relay for packets) ni njia ya akiba. Nodi mbili zinaposhindwa kufungua muunganisho wa moja kwa moja wa WireGuard, kwa kawaida kwa sababu zote ziko nyuma ya NAT (network address translation) yenye vizuizi vikali, hutuma pakiti kupitia relay badala yake. Relay haihifadhi funguo, hivyo haiwezi kusoma trafiki yako. Hata hivyo, huona ni nodi zipi zinawasiliana na kiasi cha data kinachopitishwa.

Elewa wazi kile ambacho usanidi chaguo-msingi hufanya. Headscale husambazwa ikiwa inaelekeza kwenye https://controlplane.tailscale.com/derpmap/default pamoja na auto_update_enabled: true na update_frequency: 3h, hivyo control plane ni yako huku relays zikiwa za Tailscale. Kwa watu wengi, huo ni mabadilishano unaokubalika. Ikiwa haukubali, endesha relay yako mwenyewe.

Ili kuendesha relay yako mwenyewe, weka enabled: true chini ya derp.server katika config.yaml, anzisha upya headscale, na fungua port ya STUN (session traversal utilities for NAT) kwa sudo ufw allow 3478/udp. Faili ya usanidi inaeleza sharti hilo wazi: server_url lazima itumie https, kwa sababu DERP inahitaji TLS. Kuondoa vipengee vyote kwenye orodha ya derp.urls huondoa relays za Tailscale kwenye ramani. Ukifanya hivyo bila relay iliyojengeka inayofanya kazi, jozi yoyote ya nodi ambazo haziwezi kuunganishwa moja kwa moja haziwezi kuunganishwa kabisa.

Kutoka kwa mteja, tailscale netcheck huonyesha muda wa kusubiri kwa kila eneo la relay ambalo unalijua, na tailscale status huweka kila peer alama ya ama direct yenye anwani au relay yenye msimbo wa eneo. Peer inayobaki kwenye relay ina tatizo la NAT, si tatizo la headscale.

Kwa nini node inaonekana kuwa nje ya mtandao?

Proxy inazuia upgrade. Hili ndilo tatizo la kawaida. Dalili yake ni kwamba kila kitu kingine kinaonekana kuwa sawa: /health inarudisha 200, headscale nodes list inaonyesha node, lakini node haiwahi kuwa mtandaoni. Muunganisho wa udhibiti ni POST inayobeba Upgrade: tailscale-control-protocol. Proxy ambayo haisambazi ombi hilo huondoa njia pekee ya kuripoti hali ya node. Linganisha usanidi wako wa nginx na sehemu ya map hapo juu, au tumia Caddy ili kuondoa proxy kama chanzo cha tatizo.

server_url ilibadilika baada ya nodes kujisajili. Nodes huendelea kujaribu kuunganisha kwa thamani waliyopewa wakati wa usajili. Ikiwa uliihariri, endesha sudo tailscale up --login-server https://headscale.example.com --force-reauth kwenye kila node.

Client haiendeshwi. Kwenye node, endesha sudo systemctl is-active tailscaled na sudo journalctl -u tailscaled -n 50 --no-pager. Client ambayo haiwezi kutatua au kufikia domain yako huandika majaribio yake ya kuunganisha hapo.

Key iliisha muda wake. Hili limeelezwa katika sehemu inayofuata.

Ili kufuatilia upande wa server unapojaribu, endesha sudo journalctl -u headscale -f kwenye VPS na uanzishe tena tailscaled kwenye client. Node inayofikia headscale huandika mistari ya log mara moja. Kutokuwepo kwa ujumbe kunamaanisha kuwa ombi halifiki. Kwa hiyo, kagua DNS, firewall na proxy kabla ya kukagua headscale.

Ufunguo kuisha muda wake, na node inayoacha kufanya kazi baada ya wiki kadhaa

Muda wa kuisha wa aina mbili tofauti upo, na kuzichanganya hupoteza muda.

Ufunguo wa Preauth huisha haraka kwa muundo wake. Chaguo-msingi ni saa moja na matumizi moja. Ikiwa tailscale up inakataa ufunguo, tengeneza mpya kwenye server badala ya kuhariri kitu chochote kwenye client.

Ufunguo wa node ndio sehemu inayodumu muda mrefu. Sehemu ya node ya config.yaml huweka expiry: 0, na 0 inamaanisha hakuna muda wa kuisha wa chaguo-msingi: node iliyosajiliwa hubaki halali hadi uimalizie muda wake. Node zilizo na tag hazishi muda kamwe. Weka expiry: 180d ikiwa unataka usajili uishe baada ya muda fulani, na uelewe matokeo yake: kila node isiyo na tag itahitaji sudo tailscale up --login-server https://headscale.example.com --force-reauth kwa ratiba hiyo, na server isiyo na kifaa cha kuingiza data ambayo hakuna anayeithibitisha tena itaondoka kwenye mtandao yenyewe.

Fanya hivyo kwa mkono mtu anapopoteza laptop. sudo headscale nodes list hukupa ID, kisha sudo headscale nodes expire -i 3 huondoa uhalali wa kuingia wa node hiyo, na sudo headscale nodes delete -i 3 huiondoa kabisa kwenye mtandao.

Nakala rudufu na masasisho

/var/lib/headscale na /etc/headscale kwa pamoja ndizo zinazounda seva nzima. Simamisha huduma kabla ya kuzinakili, kwa sababu SQLite huenda bado inaandika data na hifadhidata iliyonakiliwa wakati wa mzigo inaweza kuwa na taarifa zisizolingana.

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

Hamisha faili zote mbili kutoka kwenye seva. Zina funguo za faragha na kila usajili, kwa hiyo zinahitaji ulinzi sawa na seva yenyewe. nakala rudufu za restic kutoka VPS inaeleza jinsi ya kufanya hivyo kwa ratiba na kwa usimbaji fiche.

Masasisho hufuata tena hatua za usakinishaji: pakua .deb, sudo apt install ./headscale.deb mpya, kisha anzisha upya huduma na utekeleze tena ukaguzi wa is-active na /health. Tangu 0.29, njia ya masasisho ni yenye masharti makali. Kuruka toleo dogo kunazuiwa, na kushusha hadi toleo dogo la zamani pia kunazuiwa. Songa mbele kwa toleo dogo moja kwa wakati, tengeneza nakala rudufu kabla ya kila hatua, na soma kwanza maelezo ya toleo hilo, kwa sababu toleo hilo hilo lilibadilisha tabia ya sera ya ACL na kuhamisha funguo kadhaa za usanidi.

FAQ

Kwa nini headscale inashindwa kuanza mara tu baada ya kusakinisha .deb?

Kifurushi husakinisha unit lakini huacha huduma ikiwa imesimamishwa, na /etc/headscale/config.yaml chaguo-msingi ni template badala ya usanidi unaofanya kazi. Hariri server_url, listen_addr na base_domain kwanza, kisha endesha sudo systemctl enable --now headscale na uthibitishe kwa sudo systemctl is-active headscale. Ikiwa bado inashindwa, sudo journalctl -u headscale -n 50 --no-pager hutaja tatizo. Katika hatua hii, karibu kila mara huwa ni hitilafu ya YAML, kwa sababu headscale huchanganua faili lote kabla ya kuanza kusikiliza kwenye port.

Je, bado nitasakinisha mteja wa kawaida wa Tailscale kwenye mashine zangu?

Ndiyo. Headscale hubadilisha seva ya udhibiti pekee. Kila node huendesha mteja rasmi kutoka Tailscale, na unaielekeza kwenye seva yako kwa sudo tailscale up --login-server https://headscale.example.com. Flag hiyo ipo katika mteja wa kawaida, kwa hiyo hakuna kitu kinachohitaji kurekebishwa au kujengwa upya.

Je, traffic yangu hupitia kwenye seva ya headscale?

Kwa kawaida, hapana. Headscale huratibu mtandao na kusambaza keys na anwani, huku njia ya data ikiwa WireGuard ya moja kwa moja kati ya nodes zako. Traffic hupitia njia ya ziada tu wakati nodes mbili haziwezi kufikiana moja kwa moja na kulazimika kutumia relay ya DERP. Kwa usanidi uliotolewa, relay hizo ni za umma za Tailscale. Endesha tailscale status kwenye node ili kuona ikiwa peer fulani iko direct au kwenye relay.

Kwa nini node yangu hubaki offline baada ya kujisajili?

Node inayoonekana katika headscale nodes list lakini haiendi online kwa kawaida imepoteza muunganisho wake wa udhibiti kwenye reverse proxy. Muunganisho huo ni HTTP upgrade unaotumwa kama POST pamoja na header Upgrade: tailscale-control-protocol, na nginx huutupilia mbali isipokuwa uongeze block ya map $http_upgrade $connection_upgrade na mistari inayolingana ya proxy_set_header. Caddy huupitisha bila usanidi wa ziada, hivyo ni njia ya haraka ya kujaribu ikiwa proxy ndiyo chanzo cha tatizo.

Je, ninahitaji jina la domain na TLS kwa headscale?

Kwa matumizi halisi, ndiyo. Wateja huunganisha kwenye string yoyote utakayoweka katika server_url, certificates hutolewa kwa majina, si kwa anwani za IP pekee, na faili la usanidi linaeleza kuwa DERP inahitaji TLS. Domain pamoja na Caddy huchukua takribani dakika tano na hukupa endpoint ya HTTPS inayojisasisha yenyewe. Kuendesha seva ya udhibiti kwa HTTP isiyo na usimbaji kunamaanisha kuwa kila mawasiliano ya mteja nayo hupitia internet bila usimbaji.