Jinsi ya kuweka Headscale kwenye VPS yako

Headscale ni nini

Headscale ni utekelezaji wa seva ya kudhibiti (control server) ya Tailscale inayojiendesha yenyewe (self-hosted), hivyo mashine inayoratibu mtandao wako binafsi ni VPS unayomiliki. Huu ni mradi wa jamii na hauendeshwi na Tailscale Inc. Kila mashine bado inaendesha client rasmi ya tailscale, iliyoelekezwa kwenye seva yako kwa kutumia flag moja, --login-server.

Seva ya kudhibiti ndiyo sehemu inayojua nani anayehusika na mtandao huo. Inapa kila node anwani kutoka 100.64.0.0/10, inasambaza public keys, na kuwaelekeza nodes mahali pa kupatana. Tunnels hubaki kuwa za WireGuard, zilizojengwa kutoka node hadi node. Trafiki kati ya mashine zako mbili haipiti kwenye kisanduku cha headscale, isipokuwa kama njia ya moja kwa moja haiwezi kujengwa na nodes zikahitaji kutumia relay. Kuendesha jukumu hilo la uratibu wewe mwenyewe kunabadilisha nani anayelishikilia badala ya kubadilisha kile kinachoweza kufanywa, kwa hivyo ni vyema kuelewa kile ambacho seva ya kudhibiti inaweza na isichoweza kufikia katika mfumo huu kabla ya kuchukulia hatua hiyo kama ushindi wa kiusalama pekee.

Headscale huhudumia tailnet moja (mtandao mmoja wa Tailscale) kwa kila instance. Mradi unaeleza kuwa inafaa kwa matumizi binafsi au shirika dogo. Ukiwa na mashine tatu au nne, VPN ya kawaida ya WireGuard kwenye VPS unayomiliki inahitaji programu chache za kuendesha na ina vitu vichache vya kuharibika. Headscale huwa na faida pale ambapo hutaki tena kuandika mwenyewe block ya [Peer] kwa kila laptop mpya. Gharama mara nyingi ndiyo huwafanya watu waanze kutafuta suluhisho, kwa hiyo inafaa kusoma mpango wa bure wa hosted unajumuisha nini hasa kabla hujaanzisha server, kwa sababu mashine chache binafsi kwa kawaida zinaingia ndani ya mpango huo. Ikiwa tayari umevuka kikomo hicho, linganisha hesabu na gharama za mipango ya kulipia kwa kila user na resource iliyowekwa tag, kwa sababu vifaa vya user havina kikomo, huku resources zilizowekwa tag zikiwa na viwango na gharama tofauti. Ikiwa unataka control plane ya self-hosted lakini ungependa kuwa na client yako mwenyewe na web interface ya kusimamia peers badala ya replacement ya moja kwa moja ya Tailscale, NetBird kwenye VPS moja ni chaguo linalofaa kutathminiwa. Zote mbili hupitisha traffic yako kupitia WireGuard, kwa hiyo uchaguzi unategemea jinsi unavyoandika access rules na jinsi relays zinavyofanya kazi. Inafaa kulinganisha NetBird na Tailscale kuhusu mambo hayo kabla hujasakinisha mojawapo. Kwa ulinganisho mpana wa miundo hiyo miwili, soma tofauti kati ya WireGuard na Tailscale.

Mambo unayohitaji kabla ya kusakinisha

• VPS inayoendesha Ubuntu 24.04 yenye anwani ya umma ya IPv4 na ufikiaji wa sudo. Ikiwa seva ni mpya, kamilisha kwanza dakika kumi za kwanza kwenye VPS mpya.
• Rekodi ya DNS A inayoelekeza kwenye anwani hiyo. Mwongozo huu unatumia headscale.example.com.
• Domain ya pili au subdomain kwa ajili ya MagicDNS. Mwongozo huu unatumia tailnet.example.net. Hii haipaswi kuwa domain sawa na ile iliyo katika server_url.
• Mashine moja ya mteja ya kujiunga, inayoendesha Linux, macOS, Windows, Android au iOS. Headscale 0.29.6 inahitaji toleo la mteja wa Tailscale 1.80.0 au jipya zaidi.

Sakinisha headscale kutoka kwenye .deb rasmi

Mradi huu huchapisha vifurushi vya .deb kwenye ukurasa wake wa releases wa GitHub. Kufikia Oktoba 27, 2026 toleo thabiti la hivi karibuni ni 0.29.6, lililotolewa Oktoba 24, 2026. Kwanza hakiki usanifu (architecture) wa mfumo wako, kwa sababu jina la faili hubeba taarifa hiyo.

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

Hiyo huchapisha amd64 kwenye VPS ya kawaida ya x86 na arm64 kwenye mpango wa aina ya Ampere au Graviton. Weka jibu hilo kwenye kigezo (variable) hapa chini.

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

Alama ya ./ mbele ya jina la faili inahitajika. Bila hiyo, apt hutafuta kifurushi kinachoitwa headscale.deb kwenye hazina (repositories) zako na kushindwa.

Kifurushi hiki hutengeneza mtumiaji wa mfumo wa headscale, huandika /etc/headscale/config.yaml ya msingi, husakinisha unit ya systemd, na kisha huanzisha huduma hiyo. Kwa hivyo headscale inakuwa tayari inafanya kazi wakati apt inaporejea, na sudo systemctl is-active headscale huchapisha active. Hata hivyo, kwenye usakinishaji mpya, kifurushi hakiiwezeshi unit hiyo, kwa hivyo huduma haitarejea baada ya reboot hadi utakapoiwezesha, jambo ambalo hatua ya kuanzisha upya hapa chini hufanya. Pia inafanya kazi kwa kutumia configuration iliyokuja nayo, na hiyo huelekeza server_url kwenye http://127.0.0.1:8080, ambayo si anwani inayoweza kufikiwa na mteja wako yeyote. Hakuna kitu kilichofichuliwa bado, kwa sababu listen_addr iliyokuja nayo iko kwenye loopback pia, lakini usimunganishe mteja yeyote hadi utakapoweka server_url na kuanzisha upya huduma hiyo, jambo ambalo hatua mbili zinazofuata hufanya.

Sanidi server_url kabla ya mteja yeyote kujiunga

Hariri /etc/headscale/config.yaml kwa kutumia sudo nano /etc/headscale/config.yaml, au tumia mabadiliko yale yale matatu kwa kutumia sed. Hifadhi nakala ya faili asilia, kwa sababu faili hilo ni refu na lina maelezo mengi, na ndilo rejeleo bora zaidi ulilo nalo kwa ajili ya mipangilio mingine yote.

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 ya umma ambayo headscale hutumia wakati wa kutengeneza URL za usajili. Wateja hutumia anwani ya udhibiti iliyosanidiwa kwa --login-server, kwa hivyo tumia jina lile lile la umma kwa https:// katika maeneo yote mawili, kamwe usitumie 127.0.0.1. Nyaraka za headscale zinasema kuwa HTTP ya kawaida, au HTTPS kwenye port nyingine isiyo 443, inawezekana, lakini inapendekeza sana HTTPS kwenye port 443 kwa ajili ya uzalishaji (production), na mwongozo huu wote unazingatia hilo.

listen_addr ni mahali ambapo mchakato huu hufungwa (bind). Iache kwenye loopback. Reverse proxy iliyo kwenye seva hiyo hiyo hukamilisha TLS (transport layer security) na kupeleka maombi huko, kwa hivyo hakuna kitu chochote nje ya seva kinachohitaji kufikia port 8080.

base_domain ni kiambishi cha MagicDNS, kikoa ambacho nodi zako hupata majina chini yake. Lazima kiwe kikoa kilichohitimu kikamilifu (fully qualified domain name) bila nukta mwishoni, na lazima kiwe kikoa tofauti na kile kilicho kwenye server_url, kwa sababu nafasi hizo mbili za majina zingegongana.

Acha sehemu ya database kama ilivyo. Chaguo-msingi ni SQLite kwenye /var/lib/headscale/db.sqlite, katika saraka ambayo kifurushi kiliunda na kumiliki, na SQLite inatosha kwa tailnet ya ukubwa huu.

Anzisha upya headscale na uthibitishe kuwa inafanya kazi

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

is-active huchapisha active, is-enabled huchapisha enabled, na curl huchapisha 200. Kuanzisha upya ndiyo hatua inayopakia marekebisho yako. Headscale husoma usanidi wake mara moja, wakati inapoanza, kwa hivyo mchakato ulioanzishwa na kifurushi huendelea kutumia server_url iliyokuja nayo hadi utakapoiwasha upya. sudo systemctl enable --now headscale haifanyi kazi hii: huduma tayari inafanya kazi, kwa hivyo --now start haibadilishi chochote na thamani ya zamani huendelea kutumika. Kuanza wakati wa boot ni kazi ya enable, na haifanyiki kiotomatiki: kwenye usakinishaji mpya, kifurushi huanzisha huduma bila kuiwezesha, kwa hivyo endesha sudo systemctl enable headscale mara moja, kama ilivyo hapo juu.

Ikiwa is-active itachapisha kitu kingine chochote isipokuwa active, au curl haichapishi 200, soma jarida kwa kutumia sudo journalctl -u headscale -n 50 --no-pager. Kushindwa katika hatua hii karibu kila mara kunatokana na faili ya usanidi, kwa sababu headscale huchanganua faili nzima kabla ya kufungua socket, kwa hivyo indent mbaya au mpangilio wa lazima usio sahihi husimamisha mchakato kabla ya kitu chochote kusikiliza kwenye port. Rekebisha faili, kisha sudo systemctl restart headscale. Kila mabadiliko ya usanidi baadaye yanahitaji kuanzishwa upya huko huko. Wateja huunganisha tena wenyewe baadaye. Ikiwa systemd units ni ngeni kwako, kuendesha huduma na vipima muda vyako mwenyewe kwa kutumia systemd inashughulikia amri zilizotumika hapa.

Angalia faili za hali (state files) wakati uko 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 upendeleo (unprivileged user) aliyeundwa na kifurushi. noise_private.key ndiyo utambulisho wa seva kwa wateja wake. Iweke. Ukifuta, headscale itazalisha mpya na wateja lazima wachukue ufunguo mpya wa seva kabla ya kuunganisha tena; usajili uliopo unabaki kwenye database.

Weka TLS mbele ya headscale

Wateja wanapaswa kufikia server_url kupitia HTTPS. Caddy ndiyo njia ya haraka zaidi, kwa sababu huomba na kusasisha cheti chenyewe.

sudo apt install -y caddy

Badilisha /etc/caddy/Caddyfile na kizuizi kutoka kwenye nyaraka 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 wakati faili linapochanganuliwa. Onyo kwamba faili halijapangiliwa ni la kawaida tu. Kutoka kwenye laptop yako, curl -sS -o /dev/null -w '%{http_code}\\n' https://headscale.example.com/health inapaswa pia kuchapisha 200. Uthibitisho huo mmoja unaonyesha kuwa DNS, firewall, cheti na proxy zote zinafanya kazi pamoja.

Hii hapa ni maelezo ya proxy ambayo huwapa watu wakati mgumu. Muunganisho wa udhibiti wa Tailscale ni HTTP upgrade, huanzishwa kwa POST badala ya GET, na thamani ya header ya Upgrade ni tailscale-control-protocol. Caddy hupitisha hayo bila usanidi wa ziada. nginx haifanyi hivyo, kwa hivyo front end ya nginx lazima ipeleke headers za Upgrade na Connection kwa uwazi. Nyaraka za headscale hufanya hivyo kwa kutumia 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;
    }
}

Ukiacha mistari hiyo, maombi ya kawaida bado yatafanikiwa, ndiyo maana /health inarudisha 200 na kila kitu kinaonekana sawa, wakati muunganisho wa udhibiti haujawahi kutokea: nodes mpya haziwezi kujiandikisha, na nodes zilizopo haziwezi kuunganisha tena na kuripoti kuwa ziko mtandaoni. Ikiwa utatumia njia ya nginx, Certbot kwenye Ubuntu 24.04 na nginx inashughulikia nusu ya cheti.

Bandari zipi za kufungua katika UFW

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

Bandari 443 hubeba kila muunganisho wa udhibiti wa mteja kuelekea headscale. Ikiwa utawasha relay ya DERP iliyopachikwa baadaye, itahitaji pia 3478/udp, ambayo imeelezwa hapa chini. Bandari 80 ipo kwa ajili ya ACME (automatic certificate management environment) HTTP challenge na kuelekeza trafiki kwenda HTTPS. Caddy bado inaweza kupata cheti hata kama bandari 80 imefungwa, kwa sababu inaweza kutumia TLS-ALPN challenge kwenye bandari 443, lakini ikiwa 80 iko wazi, changamoto zote mbili zinapatikana na maombi ya kawaida ya http:// huelekezwa upya.

Bandari 8080 inabaki imefungwa. listen_addr ni 127.0.0.1:8080, kwa hivyo proksi hufikia headscale kupitia loopback interface na hakuna sheria ya firewall inayohusika. Kufungua 8080 katika UFW hakutafichua chochote, kwa kuwa hakuna kinachosikiliza kwenye bandari hiyo kutoka nje, na hakuna faida yoyote inayopatikana. Kumbuka kuwa watoa huduma wengi huendesha firewall ya pili katika paneli yao ya udhibiti, tofauti na UFW, kwa hivyo bandari inaweza kuwa wazi kwenye seva na bado ikawa imefungwa kwenye mpaka wa mtandao. Misingi ya UFW firewall kwenye VPS inaelezea sintaksia ya sheria kwa kina zaidi.

Unda mtumiaji na ufunguo wa preauth

sudo headscale users create alice
sudo headscale users list

Amri ya headscale ni client. Inawasiliana na daemon inayofanya kazi kupitia unix socket iliyopo /var/run/headscale/headscale.sock, ambayo ina mode 0770 na inamilikiwa na kundi la headscale. Mambo mawili yanatokana na hili. Amri hii inafeli wakati huduma imesimama, ambayo ndiyo sababu nyingine kwa nini mpangilio katika mwongozo huu ni muhimu, na inahitaji sudo isipokuwa uongeze akaunti yako kwenye kundi la headscale.

users list huchapisha ID kando ya kila jina. Unahitaji namba hiyo, kwa sababu amri ya ufunguo inahitaji numeric user ID na si jina.

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

Ufunguo huchapishwa mara moja. Nakili sasa. Ufunguo wa preauth hutumika mara moja na ni halali kwa saa moja isipokuwa ueleze vinginevyo, kwa hivyo --expiration 24h inafaa kuwekwa wakati bado unafanya majaribio. Ongeza --reusable kwa ufunguo unaoweza kusajili mashine kadhaa, na uuchukulie kama nenosiri, kwa sababu mtu yeyote aliye nao anaweza kujiunga na mtandao wako.

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 iliyotolewa na headscale, kitu kama 100.64.0.1. Ukiwa umerejea kwenye seva, sudo headscale nodes list huonyesha nodi hiyo ikiwa na ID yake, mtumiaji wake, na hali yake ya mtandaoni.

Tumia anwani ya HTTPS ya umma kutoka server_url kwa ajili ya --login-server. Mteja huondoa alama ya mkwaju (trailing slash) kutoka kwenye URL yake ya udhibiti; hakuna ulinganisho wa maandishi kamili unaokulazimu kuiondoa.

Mashine iliyokuwa imeingia awali kwenye huduma ya Tailscale inayohudumiwa na wao (hosted service) huhifadhi login hiyo. Endesha sudo tailscale logout kwenye mashine hiyo kwanza, kisha endesha tailscale up ukiwa na --login-server.

Ukiondoa --auth-key, mteja huchapisha URL badala yake. Ifungue na ukurasa utaonyesha kitambulisho cha jaribio hilo la usajili, ambacho unakikubali kwenye seva:

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

Fomu hiyo ni rahisi zaidi kwa kompyuta yako binafsi. Funguo za preauth ni bora zaidi kwa chochote kinachotumia script, kwa sababu hakuna binadamu anayehitajika kufuatilia. Mara tu VPS yenyewe inapokuwa nodi, inaweza pia kubeba trafiki ya mtandao ya mashine zako nyingine, ambayo ni usanidi wa exit node, kwa tofauti moja kwamba unakubali njia iliyotangazwa (advertised route) kwenye seva kwa kutumia amri ya headscale badala ya kufanya hivyo kwenye dashibodi ya utawala iliyohudumiwa na Tailscale. Ikiwa unachotaka ni kufikia mtandao binafsi uliopo nyuma ya VPS hiyo badala ya njia ya kutokea kwenye Internet, hatua hiyo hiyo ya idhini inashughulikia kutangaza subnet hiyo kwa mtandao wako wote wa tailnet. Kuchapisha programu moja kutoka kwenye nodi, badala ya kupitisha mitandao mizima kupitia hiyo nodi, ni kazi tofauti tena, na serve na funnel ndizo njia mbili za kufanya hivyo, ingawa zote hutegemea cheti cha Tailscale na mfumo wake wa ingress, kwa hivyo zione kama vipengele vya tailnet inayohudumiwa na Tailscale badala ya kitu ambacho headscale hukupa.

DERP, na kinachopeleka trafiki wakati njia ya moja kwa moja inaposhindwa

DERP (designated encrypted relay for packets) ndiyo njia mbadala. Wakati nodi mbili zinaposhindwa kufungua muunganisho wa moja kwa moja wa WireGuard, kwa kawaida kwa sababu zote mbili ziko nyuma ya NAT (network address translation) kali, hutuma pakiti kupitia relay badala yake. Relay haina funguo zozote, kwa hivyo haiwezi kusoma trafiki yako. Inaona ni nodi zipi zinazozungumza na kiasi gani cha data kinachopita.

Kuwa wazi kuhusu kile ambacho usanidi chaguo-msingi hufanya. Headscale inakuja ikiwa imeelekezwa kwenye https://controlplane.tailscale.com/derpmap/default pamoja na auto_update_enabled: true na update_frequency: 3h, kwa hivyo control plane ni yako wakati relays ni za Tailscale. Kwa watu wengi, huu ni ubadilishaji unaokubalika. Ikiwa sivyo, endesha relay yako mwenyewe.

Ili kuendesha relay yako mwenyewe, weka enabled: true chini ya derp.server katika config.yaml, badilisha ipv4: 198.51.100.1 na ipv6: 2001:db8::1 zilizokuja na programu kwa anwani za umma za relay yako, au ondoa mipangilio yote miwili ili kutumia DNS, kisha uanzishe upya headscale na ufungue port ya STUN (session traversal utilities for NAT) kwa kutumia sudo ufw allow 3478/udp. Mipangilio hiyo ya anwani hupuuza DNS, kwa hivyo kuacha placeholder yoyote mahali pake kutatuma wateja kwenye anwani isiyoweza kufikika. Faili ya usanidi inaeleza hitaji hilo waziwazi: server_url lazima itumie https, kwa sababu DERP inahitaji TLS. Kuondoa orodha ya derp.urls kutaondoa relays za Tailscale kutoka kwenye ramani; hakikisha una relay iliyopachikwa (embedded) au ya kawaida inayofanya kazi kabla ya kufanya hivyo. Headscale inakataa kuanza ikiwa ramani ya relay ni tupu, na ramani iliyo na relay isiyoweza kufikika pekee itawaacha wateja ambao hawawezi kuunganishwa moja kwa moja bila uwezo wa kuwasiliana.

Kutoka kwa mteja, tailscale netcheck huchapisha latency kwa kila eneo la relay linalolijua, na tailscale status huonyesha direct yenye anwani au relay yenye msimbo wa eneo kwa miunganisho amilifu ya peer. Peer aliyekwama kwenye relay anahitaji njia yake ya moja kwa moja ichunguzwe, ikiwa ni pamoja na sheria za NAT na firewall. Peer ambaye ni direct na bado ni polepole ni swali tofauti tena, na jibu la kawaida hapo ni MTU badala ya tunnel yenyewe.

Kwa nini nodi inaonekana kama iko nje ya mtandao (offline)?

Proxy inakata muunganisho wa upgrade. Dalili yake ni kwamba /health inarudisha 200 wakati usajili mpya unashindwa au nodi zilizopo haziwezi kuunganishwa tena. Muunganisho wa udhibiti ni POST inayobeba Upgrade: tailscale-control-protocol, na proxy isiyosambaza ombi hilo inazuia usajili na njia inayoripoti hali ya nodi. Linganisha usanidi wako wa nginx na mistari ya upgrade hapo juu, au tumia Caddy ili kuondoa uwezekano wa tatizo la proxy.

Anwani ya umma ya udhibiti imebadilika. Nodi zinaendelea kupiga anwani iliyosanidiwa na --login-server; kubadilisha server_url hakusasishi mpangilio huo wa mteja. Ikiwa anwani ya zamani haifikii seva yako tena, endesha sudo tailscale up --login-server https://headscale.example.com --force-reauth kwenye kila nodi.

Mteja haendeshi. Kwenye nodi, tumia sudo systemctl is-active tailscaled na sudo journalctl -u tailscaled -n 50 --no-pager. Mteja asiyeweza kutatua au kufikia domain yako huandika majaribio yake ya kurudia huko.

Ufunguo (key) umekwisha muda wake. Hili limefafanuliwa katika sehemu inayofuata.

Ili kufuatilia upande wa seva wakati unafanya majaribio, endesha sudo journalctl -u headscale -f kwenye VPS na uanzishe upya tailscaled kwenye mteja. Angalia pia jarida (journal) la mteja: ombi linalofika kwenye headscale halihakikishiwi kutoa mstari katika kiwango cha kawaida cha logi, kwa hivyo ukimya wa logi ya seva pekee hauthibitishi kutokea kwa hitilafu ya DNS, firewall, au proxy.

Kuisha kwa muda wa ufunguo, na nodi inayoacha kufanya kazi baada ya wiki kadhaa

Kuna aina mbili tofauti za kuisha kwa muda, na kuzichanganya hupoteza muda.

Preauth keys huisha muda wake haraka kwa usanifu. Muda chaguo-msingi ni saa moja na matumizi moja. Ikiwa tailscale up itakataa ufunguo, tengeneza ufunguo mpya kwenye seva badala ya kuhariri chochote kwenye mteja (client).

Node keys ndizo zenye muda mrefu wa kuishi. Sehemu ya node ya config.yaml huweka expiry: 0, na 0 inamaanisha hakuna muda chaguo-msingi wa kuisha; muda wa kuisha ulioainishwa na mteja au muda wa kuisha wa OIDC bado unaweza kutumika. Nodi zilizowekewa tag haziguswi na kuisha kwa muda kiotomatiki, ingawa msimamizi anaweza kuzifanya ziishe muda wake kwa makusudi. Weka expiry: 180d ikiwa unataka muda chaguo-msingi wa siku 180 kwa usajili usio na tag, lakini muda wa kuisha ulioombwa na mteja una kipaumbele na OIDC inaweza kubatilisha chaguo-msingi. Kubadilisha mpangilio huu hakubadilishi usajili uliopo nyuma. Nodi yenye muda wa kuisha inahitaji uthibitishaji upya kabla ya tarehe hiyo ya mwisho, kwa kutumia sudo tailscale up --login-server https://headscale.example.com --force-reauth, na seva isiyo na mtumiaji (headless server) ambayo hakuna anayeithibitisha upya itatoka kwenye mtandao wakati usajili wake utakapokwisha.

Fanya hivi kwa mikono wakati mtu anapopoteza kompyuta ndogo. sudo headscale nodes list inakupa kitambulisho (ID), kisha sudo headscale nodes expire -i 3 inaitoa nodi hiyo kwenye mfumo (logout), na sudo headscale nodes delete -i 3 inaiondoa kabisa kwenye mtandao.

Hifadhi nakala na maboresho

/var/lib/headscale na /etc/headscale kwa pamoja ndiyo seva nzima. Simamisha huduma kabla ya kuzinakili, kwa sababu SQLite inaweza kuwa na maandishi yanayoendelea na hifadhidata inayokiliwa wakati wa mzigo inaweza kuwa na hitilafu.

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 nje ya seva. Faili hizi zina funguo za siri (private keys) na kila usajili, kwa hivyo zinahitaji uangalifu sawa na seva yenyewe. restic backups from a VPS inaelezea jinsi ya kufanya hivi kwa ratiba na kwa njia iliyosimbwa.

Maboresho hurudia mchakato wa usakinishaji: pakua .deb na sudo apt install ./headscale.deb mpya, kisha uanzishe upya na uendeshe tena ukaguzi wa is-active na /health. Tangu toleo la 0.29, njia ya kuboresha ni madhubuti. Kuruka toleo dogo (minor version) kumezuiwa, na vilevile kushusha toleo (downgrading) kwenda toleo dogo la zamani. Hamia toleo moja dogo kwa wakati mmoja, chukua nakala kabla ya kila hatua, na usome maelezo ya toleo husika kwanza, kwa sababu toleo hilo hilo lilibadilisha tabia ya sera ya ACL na kuhamisha funguo kadhaa za usanidi. Toleo la 0.29.6 pia linajumuisha masasisho ya usalama kwa uthibitishaji wa cheti na utegemezi (dependencies), kwa hivyo usakinishaji uliopo wa 0.29 unapaswa kupata toleo hili la kiraka (patch release).

FAQ

Je, headscale huanza kufanya kazi mara tu baada ya kusakinisha .deb?

Ndiyo. Kifurushi hiki huanzisha huduma mara tu kinaposakinishwa, kwenye /etc/headscale/config.yaml iliyopangwa, ambayo husikiliza kwenye loopback pekee na kuweka server_url kuwa http://127.0.0.1:8080. Kwenye usakinishaji mpya, haiiwezeshi huduma hiyo, kwa hivyo haitawaka wakati wa boot hadi utakapokimbiza sudo systemctl enable headscale. Anwani iliyopangwa haina faida kwa wateja, kwa hivyo hariri server_url, listen_addr na base_domain, kisha kimbiza sudo systemctl restart headscale na uthibitishe kwa sudo systemctl is-active headscale. Ni lazima iwe restart: headscale husoma faili wakati tu inapoanza, na enable --now kwenye huduma inayofanya kazi tayari huiwezesha kwa boot lakini haianzishi upya, kwa hivyo thamani za zamani hubaki hai. Ikiwa itashindwa baada ya kuanzisha upya, sudo journalctl -u headscale -n 50 --no-pager hutaja tatizo hilo, na katika hatua hii karibu kila mara ni kosa la YAML, kwa sababu headscale huchanganua faili nzima kabla ya kufunga port.

Je, bado nasakinisha 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 kutumia sudo tailscale up --login-server https://headscale.example.com. Flag hiyo ipo kwenye mteja wa kawaida, kwa hivyo hakuna kinachohitaji kurekebishwa au kujengwa upya.

Je, trafiki yangu hupitia kwenye seva ya headscale?

Kwa kawaida hapana. Headscale huratibu mtandao na kutoa funguo na anwani, wakati njia ya data ni WireGuard moja kwa moja kati ya node zako. Trafiki hupitia njia nyingine tu wakati node mbili haziwezi kufikiana moja kwa moja na kutumia DERP relay, na kwa usanidi uliopangwa, relay hizo ni zile za umma za Tailscale. Kimbiza tailscale status kwenye node ili kuona kama peer fulani ni direct au yuko kwenye relay.

Kwa nini node yangu hubaki nje ya mtandao baada ya kujisajili?

Node inayoonekana kwenye headscale nodes list lakini haiji mtandaoni inahitaji muunganisho wake wa udhibiti kukaguliwa, ikijumuisha reverse proxy. Muunganisho huo ni HTTP upgrade inayotumwa kama POST yenye header ya Upgrade: tailscale-control-protocol, na nginx huikataa isipokuwa ukipeleka header za Upgrade na Connection waziwazi kwa kutumia proxy_set_header, jambo ambalo usanidi hapo juu hufanya kupitia block yake ya map $http_upgrade $connection_upgrade. Kukataa header hizo pia huzuia node mpya kujisajili. Caddy hupeleka muunganisho huo bila usanidi wa ziada, jambo linaloifanya kuwa njia ya haraka ya kupima kama proxy ndiyo yenye tatizo.

Je, ninahitaji jina la domain na TLS kwa ajili ya headscale?

Kwa usanidi huu, ndiyo: tumia jina la domain na HTTPS. Vyeti vinaweza pia kufunika anwani za IP, lakini faili ya usanidi inasema kuwa DERP inahitaji TLS. Domain pamoja na Caddy huchukua kama dakika tano na kukupa HTTPS endpoint inayojihuisha yenyewe. HTTP ya kawaida inawezekana, lakini nyaraka za headscale zinapendekeza sana HTTPS kwenye port 443 kwa ajili ya uzalishaji, na zinabainisha kuwa mteja wa Tailscale huchukulia HTTPS kwenye port 443 katika hali fulani.