ద్వారా Matt Connor 2026-07-30 · అప్‌డేట్ చేయబడింది 2026-08-28

headscale తో మీ స్వంత Tailscale ఎలా నడపాలి

Q: headscale ను .deb ఇన్స్టాల్ చేసిన వెంటనే ప్రారంభించడంలో ఎందుకు విఫలమవుతుంది?

ప్యాకేజ్ unit ను ఇన్స్టాల్ చేస్తుంది, కానీ service ను stopped స్థితిలో ఉంచుతుంది. అదనంగా, default /etc/headscale/config.yaml పనిచేసే configuration కాకుండా template మాత్రమే. ముందుగా server_url, listen_addr మరియు base_domain ను edit చేయండి. తరువాత sudo systemctl enable --now headscale అమలు చేసి, sudo systemctl is-active headscale తో నిర్ధారించండి. ఇంకా విఫలమైతే, సమస్యను sudo journalctl -u headscale -n 50 --no-pager చూపిస్తుంది. ఈ దశలో కారణం దాదాపు ఎల్లప్పుడూ YAML error అయి ఉంటుంది, ఎందుకంటే headscale port కు bind కావడానికి ముందు మొత్తం file ను parse చేస్తుంది.

Q: నా node register అయిన తర్వాత కూడా offline గా ఎందుకు ఉంటుంది?

headscale nodes list లో కనిపించినా online కు రాని node సాధారణంగా reverse proxy వద్ద తన control connection ను కోల్పోయి ఉంటుంది. ఆ connection, Upgrade: tailscale-control-protocol header తో పంపే HTTP upgrade request. మీరు map $http_upgrade $connection_upgrade block మరియు దానికి సరిపోయే proxy_set_header lines జోడించకపోతే nginx దాన్ని drop చేస్తుంది. Caddy కు అదనపు configuration అవసరం లేకుండానే దీనిని forward చేస్తుంది. అందువల్ల proxy కారణమా కాదా త్వరగా పరీక్షించడానికి Caddy ఉపయోగకరంగా ఉంటుంది.

Q: headscale కోసం domain name మరియు TLS అవసరమా?

ఆచరణలో అవును. Clients server_url లో మీరు ఉంచిన string కు connect అవుతాయి. Certificates పేర్ల కోసం జారీ అవుతాయి; bare IP addresses కోసం జారీ కావు. DERP కు TLS అవసరమని configuration file పేర్కొంటుంది. Domain తో పాటు Caddy ఉపయోగిస్తే సుమారు ఐదు నిమిషాల్లో స్వయంగా renew అయ్యే HTTPS endpoint లభిస్తుంది. Control server ను plain HTTP పై నడిపితే, దానితో ప్రతి client conversation internet మీద cleartext గా వెళ్తుంది.

VPS పై మీ స్వంత Tailscale control server నడపండి. అధికారిక .deb నుంచి headscale ఇన్‌స్టాల్ చేసి, ప్రారంభానికి ముందు server_url సెట్ చేసి, మొదటి node ను జత చేయండి.

Verified Every command ran end-to-end on a fresh Ubuntu 24.04 server, July 30, 2026.

headscale అంటే ఏమిటి

headscale అనేది Tailscale control server యొక్క self-hosted అమలు. అందువల్ల మీ private network ను సమన్వయం చేసే machine మీరు స్వంతం చేసుకున్న VPS అవుతుంది. ఇది community project. దీన్ని Tailscale Inc. నిర్వహించదు. ప్రతి machine లో అధికారిక tailscale clientనే నడుస్తుంది. ఒక flag, --login-server తో దాన్ని మీ server వైపు సూచించాలి.

ఎవరు network కు చెందినవారో control server కు తెలుసు. ఇది ప్రతి node కు 100.64.0.0/10 పరిధి నుంచి ఒక address కేటాయిస్తుంది, public keys ను పంపిణీ చేస్తుంది, అలాగే nodes ఒకదానినొకటి ఎక్కడ కనుగొనాలో తెలియజేస్తుంది. Tunnels మాత్రం WireGuard గానే ఉంటాయి మరియు node-to-node గా ఏర్పడతాయి. మీ రెండు machines మధ్య traffic headscale box ద్వారా వెళ్లదు. Direct path నిర్మించలేని సందర్భంలో nodes relay కు మారితే మాత్రమే traffic దాని ద్వారా వెళ్తుంది.

ప్రతి headscale instance ఒక tailnet (ఒక Tailscale network) ను అందిస్తుంది. వ్యక్తిగత వినియోగం లేదా చిన్న organisation కు ఇది అనుకూలమని project వివరిస్తుంది. మూడు లేదా నాలుగు machines ఉన్నప్పుడు, మీ స్వంత VPS పై సాధారణ WireGuard VPN నడపడం వల్ల నిర్వహించాల్సిన software తక్కువగా ఉంటుంది మరియు విఫలమయ్యే భాగాలు కూడా తక్కువగా ఉంటాయి. ప్రతి కొత్త laptop కోసం [Peer] block ను చేతితో రాయాల్సిన అవసరం లేకుండా ఉండాలనుకున్నప్పుడు headscale ఉపయోగకరంగా ఉంటుంది. Self-hosted control plane కావాలి, కానీ Tailscale కు drop-in replacement కంటే మీ స్వంత client మరియు peers నిర్వహించడానికి web interface కావాలనుకుంటే, ఒకే VPS పై NetBird పరిగణించదగిన ప్రత్యామ్నాయం. ఈ రెండు models పై విస్తృత పోలిక కోసం WireGuard మరియు Tailscale ఎలా భిన్నంగా ఉంటాయో చూడండి.

మీరు ఇన్‌స్టాల్ చేయడానికి ముందు అవసరమైనవి

Public IPv4 address మరియు sudo access కలిగిన Ubuntu 24.04 VPS. Server కొత్తదైతే, ముందుగా కొత్త VPSలో మొదటి పది నిమిషాలు మార్గదర్శిని పూర్తి చేయండి.
ఆ address కు సూచించే DNS A record. ఈ guide లో headscale.example.com ఉపయోగించబడుతుంది.
MagicDNS కోసం రెండవ domain లేదా subdomain. ఈ guide లో tailnet.example.net ఉపయోగించబడుతుంది. ఇది server_url లో ఉన్న domain తో ఒకటే కాకూడదు.
Linux, macOS, Windows, Android లేదా iOS నడుస్తున్న, networkలో చేర్చే ఒక client machine.

అధికారిక .deb నుంచి headscale ను ఇన్‌స్టాల్ చేయండి

ప్రాజెక్ట్ తన GitHub releases పేజీలో .deb ప్యాకేజీలను విడుదల చేస్తుంది. July 2026 నాటికి ప్రస్తుత release 0.29.3. ముందుగా మీ architecture ను పరిశీలించండి, ఎందుకంటే ఫైల్ పేరు అందులోని architecture ను సూచిస్తుంది.

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

సాధారణ x86 VPSలో ఇది amd64 ను, Ampere లేదా Graviton తరహా planలో arm64 ను చూపిస్తుంది. వచ్చిన సమాధానాన్ని కింది variableలో ఉంచండి.

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

ఫైల్ పేరు ముందు ఉన్న ./ అవసరం. అది లేకపోతే apt మీ repositoriesలో headscale.deb అనే package కోసం వెతికి విఫలమవుతుంది.

ఈ package ఒక headscale system userను సృష్టించి, default /etc/headscale/config.yaml ను రాసి, systemd unitను ఇన్‌స్టాల్ చేస్తుంది. ఇది serviceను ప్రారంభించదు. అదే సరైన క్రమం. పంపిణీ చేసే configuration server_url ను http://127.0.0.1:8080 కు సూచిస్తుంది. మీ clientలు చేరుకోగల address అది కాదు. అందువల్ల ఇప్పుడు ప్రారంభించిన service నడిచినా దాని configuration తప్పుగా ఉంటుంది. ఈ దశలో sudo systemctl is-active headscale ను అమలు చేస్తే inactive ముద్రించబడుతుంది. ఇది ఊహించిన ఫలితం, లోపం కాదు.

సేవను ప్రారంభించే ముందు server_url ను configure చేయండి

sudo nano /etc/headscale/config.yaml తో /etc/headscale/config.yaml ను సవరించండి లేదా sed తో అదే మూడు మార్పులను వర్తింపజేయండి. అసలు ఫైల్ యొక్క ఒక కాపీని ఉంచండి. ఈ ఫైల్ చాలా పొడవుగా ఉంటుంది మరియు ఇందులో విస్తృతంగా వ్యాఖ్యలు ఉంటాయి. మిగిలిన settings కు ఇది మీ వద్ద ఉన్న ఉత్తమ reference.

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

ప్రతి client registration లో headscale వ్రాసే address server_url. Clients ఆ exact string కు ఎప్పటికీ dial చేస్తాయి. అందువల్ల ఇందులో https:// ముందు ఉన్న public name ఉండాలి; 127.0.0.1 మాత్రం ఎప్పుడూ ఉండకూడదు.

Process bind అయ్యే స్థలాన్ని listen_addr నిర్దేశిస్తుంది. దీన్ని loopback పై ఉంచండి. అదే server లోని reverse proxy TLS (transport layer security) ను terminate చేసి, అభ్యర్థనలను దీనికి forward చేస్తుంది. కాబట్టి server వెలుపల నుంచి port 8080 ను చేరాల్సిన అవసరం లేదు.

base_domain అనేది MagicDNS suffix. మీ nodes కు పేర్లు లభించే domain ఇది. ఇందులో trailing dot లేని fully qualified domain name ఉండాలి. ఇది server_url లోని domain కంటే భిన్నంగా ఉండాలి. లేకపోతే రెండు name spaces పరస్పరం collide అవుతాయి.

Database section ను మార్చకుండా ఉంచండి. Default గా /var/lib/headscale/db.sqlite వద్ద SQLite ఉపయోగించబడుతుంది. ఇది package సృష్టించి, దాని ఆధీనంలో ఉంచిన directory లో ఉంటుంది. ఈ పరిమాణంలోని tailnet కు SQLite సరిపోతుంది.

headscale ను ప్రారంభించి, అది నడుస్తున్నట్లు నిర్ధారించండి

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, active ను ముద్రిస్తుంది. curl, 200 ను ముద్రిస్తుంది. enable --now పని యొక్క రెండు భాగాలను చేస్తుంది: ఇది సేవను ప్రారంభిస్తుంది మరియు reboot తర్వాత ప్రారంభమయ్యేలా దాన్ని గుర్తిస్తుంది.

is-active, failed ను ముద్రిస్తే, sudo journalctl -u headscale -n 50 --no-pager తో journal ను చదవండి. ఈ దశలో వైఫల్యానికి దాదాపు ఎల్లప్పుడూ configuration file కారణమవుతుంది. headscale socket తెరవకముందే మొత్తం file ను parse చేస్తుంది. అందువల్ల తప్పు indentation లేదా తెలియని key ఉంటే, ఏదీ listen చేయకముందే process ఆగిపోతుంది. File ను సరిచేసి, తరువాత sudo systemctl restart headscale ను అమలు చేయండి. తరువాత చేసే ప్రతి configuration మార్పుకూ ఇదే restart అవసరం. ఆ తర్వాత clients స్వయంగా మళ్లీ connect అవుతాయి. systemd units మీకు కొత్తగా ఉంటే, systemdతో మీ స్వంత services మరియు timers ను నడపడం అనే విభాగంలో ఇక్కడ ఉపయోగించిన commands వివరించబడ్డాయి.

మీరు shell లో ఉన్నప్పుడే state files ను పరిశీలించండి:

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

రెండు lines కూడా package సృష్టించిన unprivileged user అయిన headscale తో ప్రారంభమవుతాయి. noise_private.key అనేది server తన clients కు ఉపయోగించే identity. దాన్ని అలాగే ఉంచండి. దాన్ని delete చేస్తే, headscale కొత్త identity ని generate చేస్తుంది. అప్పుడు ప్రతి node మళ్లీ register కావాలి.

headscale ముందు TLS అమర్చడం

క్లయింట్లు server_url ను HTTPS ద్వారా చేరుకోవాలి. Caddy సరళమైన మార్గం, ఎందుకంటే అది స్వయంగా certificate ను అభ్యర్థించి renew చేస్తుంది.

sudo apt install -y caddy

/etc/caddy/Caddyfile స్థానంలో headscale documentation లోని block ను ఉంచండి:

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

ఫైల్ parse అయితే validate, adapted config to JSON ను output చేస్తుంది. ఫైల్ format చేయలేదని వచ్చే warning కు కార్యాచరణపై ప్రభావం లేదు. మీ laptop నుంచి కూడా curl -sS -o /dev/null -w '%{http_code}\\n' https://headscale.example.com/health, 200 ను output చేయాలి. ఈ ఒక్క తనిఖీ DNS, firewall, certificate మరియు proxy కలిసి సరిగ్గా పనిచేస్తున్నాయని నిర్ధారిస్తుంది.

ఇక్కడ proxy విషయంలో చాలామందికి ఎక్కువ సమయం పట్టే వివరాలు ఉన్నాయి. Tailscale control connection ఒక HTTP upgrade. ఇది GET కు బదులుగా POST తో ప్రారంభమవుతుంది. Upgrade header విలువ tailscale-control-protocol. Caddy దీనిని అదనపు configuration లేకుండా pass through చేస్తుంది. nginx అలా చేయదు. అందువల్ల nginx front end కు 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;
    }
}

ఈ lines ను వదిలేస్తే సాధారణ requests ఇప్పటికీ విజయవంతమవుతాయి. అందుకే /health 200 ను return చేసి, అన్నీ సరిగ్గా ఉన్నట్లు కనిపిస్తాయి. కానీ ఎక్కువసేపు కొనసాగాల్సిన control connection ఏర్పడదు. మీ nodes register అయిన తర్వాత offline గా ఉంటాయి. nginx మార్గాన్ని ఎంచుకుంటే, certificate భాగం కోసం Ubuntu 24.04లో nginxతో Certbot చూడండి.

UFW లో ఏ ports తెరవాలి

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

ప్రతి client సంభాషణను Port 443 నిర్వహిస్తుంది. ACME (automatic certificate management environment) HTTP challenge మరియు HTTPS కు redirect కోసం మాత్రమే Port 80 అవసరం. Certificate పొందడానికి Caddy కి ఇది తప్పనిసరి.

Port 8080 మూసివేయబడి ఉండాలి. listen_addr అనేది 127.0.0.1:8080, కాబట్టి proxy loopback interface ద్వారా headscale ను చేరుతుంది. అందువల్ల firewall rule అవసరం లేదు. Internet కు 8080 తెరవడం వల్ల clients కు cleartext control channel అందుతుంది; దాని వల్ల ఎలాంటి ప్రయోజనం ఉండదు. చాలా providers తమ control panel లో UFW కు వేరుగా రెండవ firewall ను అమలు చేస్తారని గుర్తుంచుకోండి. అందువల్ల server లో port తెరిచి ఉన్నా, edge వద్ద అది మూసివేయబడి ఉండవచ్చు. VPS పై UFW firewall ప్రాథమికాలు లో rule syntax ను మరింత వివరంగా చూడవచ్చు.

వినియోగదారుని మరియు preauth keyని సృష్టించండి

sudo headscale users create alice
sudo headscale users list

headscale command ఒక client. ఇది /var/run/headscale/headscale.sock వద్ద ఉన్న Unix socket ద్వారా నడుస్తున్న daemonతో కమ్యూనికేట్ చేస్తుంది. ఆ socket mode 0770లో ఉండి, headscale group యాజమాన్యంలో ఉంటుంది. దీనివల్ల రెండు విషయాలు స్పష్టమవుతాయి. Service ఆపి ఉన్నప్పుడు command విఫలమవుతుంది. ఈ guideలో క్రమాన్ని పాటించడం ముఖ్యం కావడానికి ఇది మరో కారణం. అలాగే, మీ స్వంత accountను headscale groupకు జోడించకపోతే sudo అవసరం.

users list ప్రతి పేరుకు పక్కన ఒక IDని చూపిస్తుంది. మీకు ఆ సంఖ్య అవసరం, ఎందుకంటే key command పేరు కాకుండా numeric user IDని స్వీకరిస్తుంది.

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

Key ఒక్కసారి మాత్రమే చూపించబడుతుంది. ఇప్పుడే దాన్ని copy చేయండి. Preauth key single-use మరియు మీరు వేరుగా పేర్కొనకపోతే ఒక గంటపాటు చెల్లుబాటవుతుంది. అందువల్ల మీరు ఇంకా testing చేస్తున్నప్పుడు --expiration 24h సెట్ చేయడం ఉపయోగకరం. అనేక machinesను enroll చేసే key కోసం --reusable జోడించండి. దాన్ని passwordలాగా రక్షించండి, ఎందుకంటే దాన్ని కలిగి ఉన్న ఎవరైనా మీ networkలో చేరగలరు.

`--login-server` తో మీ మొదటి client ను కనెక్ట్ చేయండి

మీరు join చేయాలనుకునే machine పై:

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 headscale కేటాయించిన address ను చూపిస్తుంది. ఉదాహరణకు ఇది 100.64.0.1 లాగా ఉంటుంది. Server పైకి తిరిగి వచ్చి, sudo headscale nodes list ద్వారా node యొక్క ID, user మరియు online స్థితిని చూడవచ్చు.

--login-server విలువ server_url తో ఖచ్చితంగా సరిపోవాలి. ఇందులో scheme ఉండాలి, చివరలో slash ఉండకూడదు. ఇవి strings గా పోల్చబడతాయి. సరిపోలకపోతే client ఒక address కు register అయి, తరువాత మరో address తో మాట్లాడమని ఆదేశించబడుతుంది.

గతంలో Tailscale hosted service లో sign in చేసిన machine ఆ login ను కొనసాగిస్తుంది. ముందుగా దానిపై sudo tailscale logout అమలు చేయండి. తరువాత --login-server తో tailscale up అమలు చేయండి.

--auth-key వదిలేస్తే client బదులుగా ఒక URL ను చూపిస్తుంది. దాన్ని open చేయండి. ఆ page ఆ registration attempt కు identifier ను చూపిస్తుంది. దాన్ని server పై approve చేయండి:

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

మీ స్వంత laptop కోసం ఈ పద్ధతి సౌకర్యంగా ఉంటుంది. Script ద్వారా నడిచే వాటికి preauth keys మెరుగైనవి, ఎందుకంటే అక్కడ ఎవరైనా మానవుడు నిరంతరం గమనించాల్సిన అవసరం ఉండదు. VPS స్వయంగా ఒక node అయిన తరువాత, అది మీ ఇతర machines యొక్క internet traffic ను కూడా మోయగలదు. దీనినే exit node setup అంటారు. తేడా ఏమిటంటే advertised route ను hosted admin console లో కాకుండా, server పై headscale command తో approve చేయాలి.

DERP మరియు ప్రత్యక్ష మార్గం విఫలమైనప్పుడు ట్రాఫిక్‌ను relay చేసే విధానం

DERP (packets కోసం designated encrypted relay) fallback మార్గం. రెండు nodes ప్రత్యక్ష WireGuard connection తెరవలేనప్పుడు, సాధారణంగా రెండూ కఠినమైన NAT (network address translation) వెనుక ఉన్నప్పుడు, అవి packets ను relay ద్వారా పంపుతాయి. Relay వద్ద keys ఉండవు. కాబట్టి అది మీ traffic ను చదవలేదు. అయితే ఏ nodes పరస్పరం మాట్లాడుతున్నాయి, ఎంత data తరలుతోంది అనే విషయాలు దానికి కనిపిస్తాయి.

Default configuration ఏమి చేస్తుందో స్పష్టంగా తెలుసుకోండి. Headscale, https://controlplane.tailscale.com/derpmap/default, auto_update_enabled: true మరియు update_frequency: 3h ను సూచించే విధంగా వస్తుంది. అందువల్ల మీ control plane మీ ఆధీనంలో ఉంటుంది, కానీ relays Tailscale ఆధీనంలో ఉంటాయి. చాలా మందికి ఇది సముచితమైన మార్పిడి. అది మీకు సరిపోకపోతే, మీ స్వంత relay నడపండి.

మీ స్వంత relay నడపడానికి, config.yaml లోని derp.server కింద enabled: true ను సెట్ చేసి, headscale ను restart చేయండి. తరువాత sudo ufw allow 3478/udp తో STUN (NAT కోసం session traversal utilities) port ను తెరవండి. Configuration file ఈ అవసరాన్ని స్పష్టంగా చెబుతుంది: server_url తప్పనిసరిగా https ను ఉపయోగించాలి, ఎందుకంటే DERP కు TLS అవసరం. derp.urls list ను ఖాళీ చేస్తే map నుండి Tailscale relays తొలగిపోతాయి. పనిచేసే embedded relay లేకుండా ఇలా చేస్తే, ప్రత్యక్షంగా connect కాలేని ఏ రెండు nodes అయినా అసలు connect కాలేవు.

క్లయింట్ నుంచి tailscale netcheck తనకు తెలిసిన ప్రతి relay ప్రాంతానికి ఉన్న latency ను చూపిస్తుంది. tailscale status ప్రతి peer ను, address ఉన్న directగా లేదా region code ఉన్న relayగా గుర్తిస్తుంది. relay స్థితిలోనే నిలిచిపోయిన peer కు సమస్య NATలో ఉంటుంది; అది headscale సమస్య కాదు. peer direct స్థితిలో ఉండి ఇంకా నెమ్మదిగా ఉంటే, అది వేరే సమస్య. అలాంటి సందర్భంలో సాధారణంగా tunnel కంటే MTU కారణమై ఉంటుంది.

నోడ్ offline గా ఎందుకు కనిపిస్తుంది?

Proxy upgrade ను drop చేస్తోంది. ఇది సాధారణంగా కనిపించే కారణం. మిగతావన్నీ సరిగ్గా ఉన్నట్లు కనిపిస్తాయి: /health 200 ను return చేస్తుంది, headscale nodes list నోడ్‌ను చూపిస్తుంది, కానీ నోడ్ ఎప్పటికీ online లోకి రాదు. Control connection అనేది Upgrade: tailscale-control-protocol ను కలిగిన POST request. దాన్ని forward చేయని proxy, node state ను report చేసే ఏకైక channel ను నిలిపివేస్తుంది. మీ nginx configuration ను పైనున్న map block తో పోల్చండి. లేదా proxy కారణం కాదని నిర్ధారించడానికి Caddy కు మారండి.

Nodes register అయిన తర్వాత server_url మారింది. Registration సమయంలో ఇచ్చిన value కు nodes నిరంతరం dial చేస్తాయి. దాన్ని మార్చినట్లయితే, ప్రతి node పై sudo tailscale up --login-server https://headscale.example.com --force-reauth ను run చేయండి.

Client నడవడం లేదు. Node పై sudo systemctl is-active tailscaled మరియు sudo journalctl -u tailscaled -n 50 --no-pager ను run చేయండి. మీ domain ను resolve చేయలేని లేదా దానికి చేరుకోలేని client, తన retry ప్రయత్నాలను అక్కడ log చేస్తుంది.

Key గడువు ముగిసింది. దీని గురించి తదుపరి section లో ఉంది.

మీరు test చేస్తున్నప్పుడు server side ను monitor చేయడానికి VPS పై sudo journalctl -u headscale -f ను run చేసి, client పై tailscaled ను restart చేయండి. headscale కు చేరుకున్న node వెంటనే log lines ఉత్పత్తి చేస్తుంది. ఏ output లేకపోతే request చేరడం లేదని అర్థం. కాబట్టి headscale ను పరిశీలించే ముందు DNS, firewall మరియు proxy ను తనిఖీ చేయండి.

కీ గడువు ముగియడం, కొన్ని వారాల తర్వాత పనిచేయడం ఆపే node

రెండు వేర్వేరు గడువు వ్యవధులు ఉన్నాయి. వాటిని కలిపేస్తే సమయం వృథా అవుతుంది.

Preauth keys రూపకల్పన ప్రకారం త్వరగా expire అవుతాయి. Default గా వాటి గడువు ఒక గంట, ఒక వినియోగం. tailscale up key ను అంగీకరించకపోతే client లో ఏదైనా సవరించకుండా server పై కొత్త key రూపొందించండి.

Node keys ఎక్కువకాలం చెల్లుబాటు అయ్యే భాగం. config.yaml లోని node section expiry: 0 ను నిర్దేశిస్తుంది. 0 అంటే default expiry లేదని అర్థం: మీరు expire చేసే వరకు registered node చెల్లుబాటులో ఉంటుంది. Tagged nodes కు ఎట్టి పరిస్థితుల్లోనూ expiry ఉండదు. Registrations స్వయంచాలకంగా గడువు ముగిసేలా చేయాలనుకుంటే expiry: 180d ను సెట్ చేయండి. అయితే దాని ప్రభావాన్ని అర్థం చేసుకోండి: ప్రతి non-tagged node ఆ schedule ప్రకారం sudo tailscale up --login-server https://headscale.example.com --force-reauth చేయాలి. ఎవ్వరూ మళ్లీ authenticate చేయని headless server స్వయంగా network నుంచి తొలగిపోతుంది.

ఎవరైనా laptop కోల్పోతే దీన్ని మాన్యువల్‌గా చేయండి. sudo headscale nodes list మీకు ID ఇస్తుంది. తరువాత sudo headscale nodes expire -i 3 ఆ node ను logout చేస్తుంది. sudo headscale nodes delete -i 3 దాన్ని network నుంచి పూర్తిగా తొలగిస్తుంది.

బ్యాకప్‌లు మరియు అప్‌గ్రేడ్‌లు

/var/lib/headscale మరియు /etc/headscale కలిసి మొత్తం సర్వర్‌ను సూచిస్తాయి. వాటిని కాపీ చేయడానికి ముందు సేవను ఆపండి. SQLiteలో రాతి చర్యలు ఇంకా కొనసాగుతూ ఉండవచ్చు. Loadలో ఉన్న databaseను కాపీ చేస్తే అది inconsistentగా ఉండవచ్చు.

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

రెండు ఫైళ్లను server వెలుపలికి తరలించండి. వాటిలో private keys మరియు అన్ని registrations ఉంటాయి. అందువల్ల వాటిని serverకే ఇచ్చే స్థాయి జాగ్రత్తతో నిర్వహించాలి. VPS నుంచి restic backups ను షెడ్యూల్ ప్రకారం, encryptionతో చేయడం గురించి వివరిస్తుంది.

Upgrades సమయంలో install ప్రక్రియనే మళ్లీ అనుసరించాలి: కొత్త .deb, sudo apt install ./headscale.deb ను download చేసి, తరువాత restart చేసి is-active మరియు /health checks ను మళ్లీ అమలు చేయండి. 0.29 నుంచి upgrade path కఠినంగా ఉంది. Minor version దాటడం నిరోధించబడుతుంది. పాత minor versionకు downgrade చేయడం కూడా నిరోధించబడుతుంది. ఒక్కసారి ఒక minor version చొప్పున upgrade చేయండి. ప్రతి దశకు ముందు backup తీసుకోండి. ముందుగా ఆ version release notes చదవండి. ఎందుకంటే అదే release ACL policy ప్రవర్తనను మార్చి, అనేక configuration keys స్థానాలను మార్చింది.

FAQ

headscale ను .deb ఇన్‌స్టాల్ చేసిన వెంటనే ప్రారంభించడంలో ఎందుకు విఫలమవుతుంది?

ప్యాకేజ్ unit ను ఇన్‌స్టాల్ చేస్తుంది, కానీ service ను stopped స్థితిలో ఉంచుతుంది. అదనంగా, default /etc/headscale/config.yaml పనిచేసే configuration కాకుండా template మాత్రమే. ముందుగా server_url, listen_addr మరియు base_domain ను edit చేయండి. తరువాత sudo systemctl enable --now headscale అమలు చేసి, sudo systemctl is-active headscale తో నిర్ధారించండి. ఇంకా విఫలమైతే, సమస్యను sudo journalctl -u headscale -n 50 --no-pager చూపిస్తుంది. ఈ దశలో కారణం దాదాపు ఎల్లప్పుడూ YAML error అయి ఉంటుంది, ఎందుకంటే headscale port కు bind కావడానికి ముందు మొత్తం file ను parse చేస్తుంది.

నా machines లో సాధారణ Tailscale client ను ఇంకా ఇన్‌స్టాల్ చేయాలా?

అవును. headscale control server ను మాత్రమే భర్తీ చేస్తుంది. ప్రతి node Tailscale అందించే official client ను నడుపుతుంది. sudo tailscale up --login-server https://headscale.example.com తో ఆ client ను మీ server వైపు point చేయండి. ఆ flag standard client లోనే ఉంటుంది. అందువల్ల patching లేదా rebuilding అవసరం లేదు.

నా traffic headscale server ద్వారా వెళ్తుందా?

సాధారణంగా వెళ్లదు. headscale network ను coordinate చేసి keys మరియు addresses ను అందిస్తుంది. Data path మాత్రం మీ nodes మధ్య నేరుగా WireGuard ద్వారా ఉంటుంది. రెండు nodes ఒకదానికొకటి నేరుగా చేరుకోలేనప్పుడు మాత్రమే traffic DERP relay ద్వారా వెళ్తుంది. Shipped configuration లో ఆ relays Tailscale యొక్క public relays గా ఉంటాయి. ఒక node పై tailscale status అమలు చేసి, నిర్దిష్ట peer direct లో ఉందా లేదా relay లో ఉందా చూడండి.

నా node register అయిన తర్వాత కూడా offline గా ఎందుకు ఉంటుంది?

headscale nodes list లో కనిపించినా online కు రాని node సాధారణంగా reverse proxy వద్ద తన control connection ను కోల్పోయి ఉంటుంది. ఆ connection, Upgrade: tailscale-control-protocol header తో పంపే HTTP upgrade request. మీరు map $http_upgrade $connection_upgrade block మరియు దానికి సరిపోయే proxy_set_header lines జోడించకపోతే nginx దాన్ని drop చేస్తుంది. Caddy కు అదనపు configuration అవసరం లేకుండానే దీనిని forward చేస్తుంది. అందువల్ల proxy కారణమా కాదా త్వరగా పరీక్షించడానికి Caddy ఉపయోగకరంగా ఉంటుంది.

headscale కోసం domain name మరియు TLS అవసరమా?

ఆచరణలో అవును. Clients server_url లో మీరు ఉంచిన string కు connect అవుతాయి. Certificates పేర్ల కోసం జారీ అవుతాయి; bare IP addresses కోసం జారీ కావు. DERP కు TLS అవసరమని configuration file పేర్కొంటుంది. Domain తో పాటు Caddy ఉపయోగిస్తే సుమారు ఐదు నిమిషాల్లో స్వయంగా renew అయ్యే HTTPS endpoint లభిస్తుంది. Control server ను plain HTTP పై నడిపితే, దానితో ప్రతి client conversation internet మీద cleartext గా వెళ్తుంది.

#headscale #tailscale #wireguard #vpn #self-hosting

headscale అంటే ఏమిటి

మీరు ఇన్‌స్టాల్ చేయడానికి ముందు అవసరమైనవి

అధికారిక .deb నుంచి headscale ను ఇన్‌స్టాల్ చేయండి

సేవను ప్రారంభించే ముందు server_url ను configure చేయండి

headscale ను ప్రారంభించి, అది నడుస్తున్నట్లు నిర్ధారించండి

headscale ముందు TLS అమర్చడం

UFW లో ఏ ports తెరవాలి

వినియోగదారుని మరియు preauth keyని సృష్టించండి

--login-server తో మీ మొదటి client ను కనెక్ట్ చేయండి

DERP మరియు ప్రత్యక్ష మార్గం విఫలమైనప్పుడు ట్రాఫిక్‌ను relay చేసే విధానం

నోడ్ offline గా ఎందుకు కనిపిస్తుంది?

కీ గడువు ముగియడం, కొన్ని వారాల తర్వాత పనిచేయడం ఆపే node

బ్యాకప్‌లు మరియు అప్‌గ్రేడ్‌లు

FAQ

headscale ను .deb ఇన్‌స్టాల్ చేసిన వెంటనే ప్రారంభించడంలో ఎందుకు విఫలమవుతుంది?

నా machines లో సాధారణ Tailscale client ను ఇంకా ఇన్‌స్టాల్ చేయాలా?

నా traffic headscale server ద్వారా వెళ్తుందా?

నా node register అయిన తర్వాత కూడా offline గా ఎందుకు ఉంటుంది?

headscale కోసం domain name మరియు TLS అవసరమా?

`--login-server` తో మీ మొదటి client ను కనెక్ట్ చేయండి