headscale سے اپنا Tailscale سرور کیسے چلائیں

headscale کیا ہے

headscale، Tailscale control server کا self-hosted implementation ہے۔ اس لیے آپ کے private network کو coordinate کرنے والی مشین آپ کی ملکیت کا VPS ہوتی ہے۔ یہ community project ہے اور اسے Tailscale Inc. نہیں چلاتی۔ ہر مشین پر official tailscale client چلتا رہتا ہے، جسے ایک flag، --login-server کے ذریعے آپ کے server کی طرف متوجہ کیا جاتا ہے۔

Control server network میں شامل مشینوں کی شناخت رکھتا ہے۔ یہ ہر node کو 100.64.0.0/10 میں سے ایک address دیتا ہے، public keys تقسیم کرتا ہے، اور nodes کو بتاتا ہے کہ وہ ایک دوسرے کو کہاں تلاش کریں۔ Tunnels بدستور WireGuard رہتے ہیں اور node سے node تک بنتے ہیں۔ آپ کی دو مشینوں کے درمیان traffic headscale box سے نہیں گزرتا، الا یہ کہ direct path قائم نہ ہو سکے اور nodes relay استعمال کرنے لگیں۔

headscale کی ہر instance ایک tailnet، یعنی ایک Tailscale network، فراہم کرتی ہے۔ project کے مطابق یہ ذاتی استعمال یا چھوٹی organisation کے لیے موزوں ہے۔ اگر آپ کے پاس تین یا چار مشینیں ہیں تو اپنی ملکیت کے VPS پر سادہ WireGuard VPN چلانا کم software اور کم قابلِ خرابی configuration کا تقاضا کرتا ہے۔ headscale اس وقت مفید ہوتا ہے جب آپ ہر نئے laptop کے لیے [Peer] block دستی طور پر نہیں لکھنا چاہتے۔ اگر آپ self-hosted control plane چاہتے ہیں، لیکن Tailscale کے drop-in replacement کے بجائے اپنا client اور peers manage کرنے کے لیے web interface پسند کرتے ہیں، تو ایک VPS پر NetBird قابلِ غور متبادل ہے۔ دونوں models کے وسیع تر موازنے کے لیے WireGuard اور Tailscale کے فرق دیکھیں۔

انسٹال کرنے سے پہلے درکار چیزیں

• Ubuntu 24.04 چلانے والا VPS، جس کے پاس public IPv4 address اور sudo access ہو۔ اگر server نیا ہے تو پہلے نئے VPS کے پہلے دس منٹ مکمل کریں۔
• اس address کی طرف اشارہ کرنے والا DNS A record۔ اس guide میں headscale.example.com استعمال کیا گیا ہے۔
• MagicDNS کے لیے دوسرا domain یا subdomain۔ اس guide میں tailnet.example.net استعمال کیا گیا ہے۔ یہ server_url میں موجود domain جیسا نہیں ہونا چاہیے۔
• شامل کرنے کے لیے ایک client machine، جس پر Linux، macOS، Windows، Android یا iOS چل رہا ہو۔

سرکاری .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 نامی پیکیج تلاش کرتا ہے اور ناکام ہو جاتا ہے۔

یہ پیکیج headscale system user بناتا ہے، ایک default /etc/headscale/config.yaml لکھتا ہے، اور systemd unit انسٹال کرتا ہے۔ یہ service شروع نہیں کرتا، اور یہی درست ترتیب ہے۔ فراہم کردہ configuration server_url کو http://127.0.0.1:8080 کی طرف متوجہ کرتی ہے، جو ایسا address نہیں ہے جس تک آپ کا کوئی client پہنچ سکے۔ اس لیے اگر service ابھی شروع ہو بھی جائے تو configuration غلط ہو گی۔ اس مرحلے پر sudo systemctl is-active headscale چلانے سے inactive پرنٹ ہوتا ہے۔ یہ متوقع نتیجہ ہے، خرابی نہیں۔

سروس شروع کرنے سے پہلے server_url ترتیب دیں

/etc/headscale/config.yaml کو sudo nano /etc/headscale/config.yaml کے ذریعے ترمیم کریں، یا sed کے ذریعے یہی تین تبدیلیاں لاگو کریں۔ اصل فائل کی ایک نقل محفوظ رکھیں، کیونکہ یہ فائل طویل اور تفصیلی تبصروں سے بھری ہوئی ہے، اور باقی settings کے لیے آپ کے پاس موجود بہترین حوالہ یہی ہے۔

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 وہ address ہے جسے headscale ہر client registration میں لکھتا ہے۔ Clients اس کے بعد ہمیشہ اسی exact string سے رابطہ کرتے ہیں، اس لیے یہاں public name کے آگے https:// ہونا ضروری ہے، 127.0.0.1 نہیں۔

listen_addr وہ address ہے جہاں process bind ہوتا ہے۔ اسے loopback پر رہنے دیں۔ اسی server پر موجود reverse proxy TLS (transport layer security) terminate کرتا ہے اور درخواستیں اس process کو forward کرتا ہے، اس لیے server کے باہر سے کسی کو port 8080 تک پہنچنے کی ضرورت نہیں۔

base_domain MagicDNS suffix ہے؛ یعنی وہ domain جس کے تحت آپ کے nodes کو names ملتے ہیں۔ یہ trailing dot کے بغیر fully qualified domain name ہونا چاہیے، اور server_url میں موجود domain سے مختلف ہونا چاہیے، کیونکہ بصورتِ دیگر دونوں name spaces آپس میں متصادم ہو جائیں گی۔

database section کو تبدیل نہ کریں۔ default /var/lib/headscale/db.sqlite پر SQLite ہے، ایسی directory میں جسے package نے بنایا اور own کیا ہے، اور اس سائز کے 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 کام کے دونوں حصے انجام دیتا ہے: یہ service شروع کرتا ہے اور reboot کے بعد اسے خودکار طور پر شروع ہونے کے لیے فعال کرتا ہے۔

اگر is-active، failed دکھائے تو sudo journalctl -u headscale -n 50 --no-pager سے journal پڑھیں۔ اس مرحلے پر failure تقریباً ہمیشہ configuration file کی وجہ سے ہوتا ہے، کیونکہ headscale socket کھولنے سے پہلے پوری file parse کرتا ہے۔ اس لیے غلط indentation یا نامعلوم key، process کو اس مقام سے پہلے روک دیتی ہے جہاں کوئی چیز listen کر رہی ہو۔ 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 headscale سے شروع ہوتی ہیں، جو اس package کے بنائے ہوئے غیر مراعات یافتہ user کا نام ہے۔ noise_private.key، clients کے لیے server کی شناخت ہے۔ اسے محفوظ رکھیں۔ اگر آپ اسے حذف کر دیں تو headscale نئی شناخت بنائے گا اور ہر node کو دوبارہ register کرنا ہوگا۔

headscale کے سامنے TLS رکھیں

کلائنٹس کو server_url تک HTTPS کے ذریعے پہنچنا چاہیے۔ Caddy سب سے مختصر راستہ ہے، کیونکہ یہ خود certificate طلب کرتا اور renew کرتا ہے۔

sudo apt install -y caddy

/etc/caddy/Caddyfile کو headscale کی documentation کے block سے replace کریں:

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 دکھاتا ہے۔ فائل کے format نہ ہونے سے متعلق warning صرف ظاہری مسئلہ ہے۔ اپنے laptop سے curl -sS -o /dev/null -w '%{http_code}\\n' https://headscale.example.com/health کو بھی 200 دکھانا چاہیے۔ یہ واحد check ثابت کرتا ہے کہ DNS، firewall، certificate اور proxy مل کر درست کام کر رہے ہیں۔

یہاں proxy کی وہ تفصیل ہے جس کی وجہ سے لوگوں کا پورا ایک شام ضائع ہو جاتا ہے۔ Tailscale control connection ایک HTTP upgrade ہے۔ اسے GET کے بجائے POST سے شروع کیا جاتا ہے، اور Upgrade header کی value tailscale-control-protocol ہے۔ Caddy اسے اضافی configuration کے بغیر آگے منتقل کر دیتا ہے۔ 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 واپس کرتا ہے اور سب کچھ درست نظر آتا ہے، لیکن دیر تک قائم رہنے والا control connection نہیں بنتا۔ آپ کے nodes register ہونے کے بعد offline رہتے ہیں۔ اگر آپ nginx استعمال کریں تو Ubuntu 24.04 پر nginx کے ساتھ Certbot certificate والے حصے کا طریقہ بیان کرتا ہے۔

UFW میں کون سے ports کھولنے ہیں

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

Port 443 ہر client کی تمام گفتگو منتقل کرتا ہے۔ Port 80 صرف ACME (automatic certificate management environment) کے HTTP challenge اور HTTPS پر redirect کے لیے ہے، اور Caddy کو certificate حاصل کرنے کے لیے اس کی ضرورت ہوتی ہے۔

Port 8080 بند رہتا ہے۔ listen_addr، 127.0.0.1:8080 ہے، اس لیے proxy، headscale تک loopback interface کے ذریعے پہنچتا ہے اور firewall rule کی ضرورت نہیں ہوتی۔ Port 8080 کو internet کے لیے کھولنے سے clients کو cleartext control channel ملتا ہے، لیکن اس کا کوئی فائدہ نہیں۔ یاد رکھیں کہ زیادہ تر providers اپنے control panel میں UFW سے الگ دوسرا firewall چلاتے ہیں۔ اس لیے box پر کوئی port کھلا ہو سکتا ہے، لیکن edge پر پھر بھی بند ہو سکتا ہے۔ VPS پر UFW firewall کی بنیادی باتیں میں rule syntax کی مزید تفصیل دی گئی ہے۔

صارف اور preauth key بنائیں

sudo headscale users create alice
sudo headscale users list

headscale کمانڈ ایک client ہے۔ یہ چلتے ہوئے daemon سے /var/run/headscale/headscale.sock پر موجود Unix socket کے ذریعے رابطہ کرتی ہے، جو mode 0770 رکھتا ہے اور headscale group کی ملکیت ہے۔ اس کے دو نتائج ہیں۔ سروس بند ہونے کی صورت میں کمانڈ ناکام ہو جاتی ہے، جو اس گائیڈ میں ترتیب کی اہمیت کی ایک اور وجہ ہے۔ اس کمانڈ کے لیے sudo درکار ہے، جب تک آپ اپنا account headscale group میں شامل نہ کر دیں۔

users list ہر نام کے ساتھ ایک ID دکھاتا ہے۔ آپ کو یہ number درکار ہے، کیونکہ key command نام کے بجائے numeric user ID لیتی ہے۔

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

Key صرف ایک بار دکھائی جاتی ہے۔ اسے ابھی copy کر لیں۔ Preauth key single use ہوتی ہے اور ایک گھنٹے تک valid رہتی ہے، جب تک آپ مختلف مدت مقرر نہ کریں۔ اس لیے testing کے دوران --expiration 24h مقرر کرنا مفید ہے۔ متعدد machines کو enroll کرنے والی key کے لیے --reusable شامل کریں، اور اسے password کی طرح محفوظ رکھیں، کیونکہ جس شخص کے پاس یہ key ہو وہ آپ کے network میں شامل ہو سکتا ہے۔

اپنے پہلے client کو --login-server کے ساتھ connect کریں

جس 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 وہ address دکھاتا ہے جو headscale نے assign کیا ہے، مثلاً 100.64.0.1۔ پھر server پر sudo headscale nodes list node کو اس کی ID، user اور online state کے ساتھ دکھاتا ہے۔

--login-server کی value کو server_url سے بالکل match کرنا چاہیے۔ اس میں scheme بھی شامل ہونی چاہیے اور آخر میں trailing slash نہیں ہونی چاہیے۔ ان values کا موازنہ strings کے طور پر کیا جاتا ہے۔ عدم مطابقت کی صورت میں client ایک address پر register ہوتا ہے، پھر اسے دوسرے address سے رابطہ کرنے کی ہدایت ملتی ہے۔

جو machine پہلے Tailscale کی hosted service میں sign in کر چکی ہو، وہ اسی login کو برقرار رکھتی ہے۔ پہلے اس پر sudo tailscale logout چلائیں، پھر tailscale up کو --login-server کے ساتھ چلائیں۔

اگر --auth-key چھوڑ دیں تو client اس کے بجائے ایک URL دکھاتا ہے۔ اسے کھولیں۔ صفحہ اس registration attempt کا identifier دکھاتا ہے، جسے server پر approve کریں:

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

یہ طریقہ اپنے laptop کے لیے زیادہ آسان ہے۔ scripted کاموں کے لیے preauth keys بہتر ہیں، کیونکہ کسی انسان کو نگرانی کرنے کی ضرورت نہیں ہوتی۔ VPS خود node بن جائے تو وہ آپ کی دوسری machines کا internet traffic بھی منتقل کر سکتا ہے۔ یہ exit node setup ہے۔ فرق صرف یہ ہے کہ advertised route کو hosted admin console کے بجائے server پر headscale command سے approve کیا جاتا ہے۔

DERP، اور براہِ راست راستہ ناکام ہونے پر ٹریفک کون relay کرتا ہے

DERP (designated encrypted relay for packets) fallback path ہے۔ جب دو nodes براہِ راست WireGuard connection قائم نہیں کر سکتے، عموماً اس لیے کہ دونوں strict 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 کے ساتھ ship ہوتا ہے، اس لیے آپ کا control plane آپ کی ملکیت رہتا ہے، جبکہ relays Tailscale کے ہوتے ہیں۔ زیادہ تر لوگوں کے لیے یہ مناسب سمجھوتا ہے۔ اگر ایسا نہیں ہے تو اپنا relay چلائیں۔

اپنا relay چلانے کے لیے config.yaml میں derp.server کے تحت enabled: true مقرر کریں، headscale restart کریں، اور sudo ufw allow 3478/udp کے ساتھ STUN (session traversal utilities for NAT) port کھولیں۔ Configuration file اس ضرورت کو واضح طور پر بیان کرتی ہے: server_url میں https استعمال ہونا چاہیے، کیونکہ DERP کو TLS درکار ہے۔ derp.urls list خالی کرنے سے Tailscale کے relays map سے حذف ہو جاتے ہیں۔ اگر آپ working embedded relay کے بغیر ایسا کریں تو nodes کا ہر وہ جوڑا جو براہِ راست connect نہیں ہو سکتا، بالکل connect نہیں ہو سکے گا۔

کلائنٹ سے tailscale netcheck ہر اس relay region تک latency دکھاتا ہے جس سے وہ واقف ہے، جبکہ tailscale status ہر peer کو یا تو پتے کے ساتھ direct یا region code کے ساتھ relay کے طور پر نشان زد کرتا ہے۔ relay پر رکا ہوا peer NAT کا مسئلہ ہے، headscale کا نہیں۔ جو peer direct ہو لیکن پھر بھی سست ہو، وہ ایک الگ مسئلہ ہے، اور اس کا عمومی جواب tunnel کے بجائے MTU ہوتا ہے۔

نوڈ offline کیوں دکھائی دیتا ہے؟

Proxy upgrade کو drop کر رہا ہے۔ یہ عام وجہ ہے، اور اس کی علامت یہ ہے کہ باقی سب کچھ درست دکھائی دیتا ہے: /health کا جواب 200 آتا ہے، headscale nodes list نوڈ دکھاتا ہے، لیکن نوڈ کبھی online نہیں ہوتا۔ Control connection ایک POST ہے جس میں Upgrade: tailscale-control-protocol شامل ہوتا ہے۔ جو proxy اسے forward نہ کرے، وہ نوڈ کی state رپورٹ کرنے والے واحد channel کو ختم کر دیتا ہے۔ اپنی nginx configuration کا اوپر دیے گئے map block سے موازنہ کریں، یا proxy کو خارج از امکان قرار دینے کے لیے Caddy استعمال کریں۔

نوڈز کے register ہونے کے بعد server_url تبدیل کر دیا گیا۔ نوڈز registration کے وقت دی گئی value پر ہی connection بنانے کی کوشش کرتے رہتے ہیں۔ اگر آپ نے اسے edit کیا ہے تو ہر نوڈ پر sudo tailscale up --login-server https://headscale.example.com --force-reauth چلائیں۔

Client چل نہیں رہا۔ نوڈ پر sudo systemctl is-active tailscaled اور sudo journalctl -u tailscaled -n 50 --no-pager چلائیں۔ جو client آپ کے domain کو resolve یا reach نہ کر سکے، وہ اپنی retry کی معلومات وہیں log کرتا ہے۔

Key expire ہو گئی ہے۔ اس کی وضاحت اگلے section میں ہے۔

Test کرتے وقت server side کو monitor کرنے کے لیے VPS پر sudo journalctl -u headscale -f چلائیں اور client پر tailscaled restart کریں۔ جو نوڈ headscale تک پہنچتا ہے، وہ فوراً log lines پیدا کرتا ہے۔ خاموشی کا مطلب ہے کہ request پہنچ نہیں رہی۔ اس لیے headscale دیکھنے سے پہلے DNS، firewall اور proxy کی جانچ کریں۔

کلید کی میعاد ختم ہونا، اور وہ node جو چند ہفتے بعد کام کرنا بند کر دیتا ہے

دو الگ میعادیں موجود ہیں، اور انہیں آپس میں ملانے سے وقت ضائع ہوتا ہے۔

Preauth keys جان بوجھ کر جلدی expire ہوتی ہیں۔ ڈیفالٹ ایک گھنٹہ اور ایک استعمال ہے۔ اگر tailscale up key قبول نہ کرے تو client پر کچھ بھی edit کرنے کے بجائے server پر نئی key generate کریں۔

Node keys طویل مدتی حصہ ہیں۔ config.yaml کا node section expiry: 0 متعین کرتا ہے، اور 0 کا مطلب ہے کہ کوئی default expiry نہیں ہے: registered node کو expire کرنے تک وہ valid رہتا ہے۔ Tagged nodes کی expiry کبھی نہیں ہوتی۔ اگر آپ registrations کو وقت کے ساتھ expire کرنا چاہتے ہیں تو expiry: 180d set کریں، اور اس کا مطلب سمجھیں: اس کے بعد ہر non-tagged node کو اسی schedule کے مطابق sudo tailscale up --login-server https://headscale.example.com --force-reauth درکار ہوگا، اور ایک headless server جسے کوئی دوبارہ authenticate نہیں کرتا، خود ہی network سے خارج ہو جائے گا۔

جب کوئی laptop گم کر دے تو یہ کام دستی طور پر کریں۔ sudo headscale nodes list آپ کو ID دیتا ہے، پھر sudo headscale nodes expire -i 3 اس node کو log out کرتا ہے، اور sudo headscale nodes delete -i 3 اسے network سے مکمل طور پر remove کر دیتا ہے۔

بیک اپ اور اپ گریڈ

/var/lib/headscale اور /etc/headscale مل کر پورا سرور تشکیل دیتے ہیں۔ انہیں copy کرنے سے پہلے service روک دیں، کیونکہ SQLite میں writes جاری ہو سکتی ہیں اور load کے دوران copy کیا گیا 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

دونوں files کو server سے باہر منتقل کریں۔ ان میں private keys اور تمام registrations موجود ہوتی ہیں، اس لیے ان کی حفاظت بھی server جیسی کریں۔ VPS سے restic بیک اپ میں اسے مقررہ schedule کے مطابق اور encrypted طریقے سے کرنے کا طریقہ بتایا گیا ہے۔

اپ گریڈ میں install کا عمل دہرایا جاتا ہے: نیا .deb، sudo apt install ./headscale.deb download کریں، پھر service restart کریں اور is-active اور /health checks دوبارہ چلائیں۔ 0.29 کے بعد upgrade path سخت ہے۔ minor version چھوڑ کر اپ گریڈ کرنا blocked ہے، اور کسی پرانے minor version پر downgrade کرنا بھی blocked ہے۔ ایک وقت میں صرف ایک minor version آگے بڑھیں، ہر مرحلے سے پہلے backup لیں، اور پہلے اس version کے release notes پڑھیں، کیونکہ اسی release میں ACL policy کا behaviour تبدیل ہوا اور کئی configuration keys منتقل کی گئیں۔

FAQ

headscale کو install کرنے کے فوراً بعد start ہونے میں ناکامی کیوں ہوتی ہے؟

Package unit install کر دیتا ہے، لیکن service کو stopped حالت میں چھوڑ دیتا ہے، اور default /etc/headscale/config.yaml کام کرنے والی configuration کے بجائے template ہوتی ہے۔ پہلے server_url، listen_addr اور base_domain میں ترمیم کریں، پھر sudo systemctl enable --now headscale چلائیں اور sudo systemctl is-active headscale سے تصدیق کریں۔ اگر پھر بھی failure ہو تو sudo journalctl -u headscale -n 50 --no-pager مسئلے کی نشاندہی کرے گا۔ اس مرحلے پر وجہ تقریباً ہمیشہ YAML error ہوتی ہے، کیونکہ headscale port پر bind ہونے سے پہلے پوری file کو parse کرتا ہے۔

کیا مجھے اپنی مشینوں پر معمول کا Tailscale client اب بھی install کرنا ہوگا؟

جی ہاں۔ Headscale صرف control server کی جگہ لیتا ہے۔ ہر node Tailscale کا official client چلاتا ہے، اور sudo tailscale up --login-server https://headscale.example.com کے ذریعے اسے اپنے server کی طرف متوجہ کرتے ہیں۔ یہ flag standard client میں موجود ہے، اس لیے کسی patch یا rebuild کی ضرورت نہیں۔

کیا میرا network traffic headscale server سے گزرتا ہے؟

عام طور پر نہیں۔ Headscale network کو coordinate کرتا ہے اور keys اور addresses فراہم کرتا ہے، جبکہ data path آپ کے nodes کے درمیان براہ راست WireGuard کے ذریعے قائم ہوتا ہے۔ Traffic صرف اس وقت متبادل راستہ اختیار کرتا ہے جب دو nodes ایک دوسرے تک براہ راست نہ پہنچ سکیں اور DERP relay استعمال کریں۔ Shipped configuration میں یہ relays Tailscale کے public relays ہوتے ہیں۔ کسی node پر tailscale status چلائیں تاکہ معلوم ہو سکے کہ کوئی مخصوص peer direct ہے یا relay پر ہے۔

میرے node کے register ہونے کے بعد بھی وہ offline کیوں رہتا ہے؟

جو node headscale nodes list میں ظاہر ہو لیکن کبھی online نہ ہو، عموماً اس کا reverse proxy کے ساتھ control connection ختم ہو چکا ہوتا ہے۔ یہ connection Upgrade: tailscale-control-protocol header کے ساتھ بھیجا جانے والا HTTP upgrade ہوتا ہے، اور nginx اسے اس وقت تک drop کر دیتا ہے جب تک آپ map $http_upgrade $connection_upgrade block اور متعلقہ proxy_set_header lines شامل نہ کریں۔ Caddy اسے اضافی configuration کے بغیر forward کر دیتا ہے۔ اس لیے یہ جانچنے کا تیز طریقہ ہے کہ مسئلہ proxy میں ہے یا نہیں۔

کیا headscale کے لیے domain name اور TLS درکار ہیں؟

عملی طور پر، جی ہاں۔ Clients server_url میں درج string سے connect کرتے ہیں، certificates names کے لیے جاری ہوتے ہیں، bare IP addresses کے لیے نہیں، اور configuration file کے مطابق DERP کے لیے TLS ضروری ہے۔ Domain اور Caddy کے ذریعے تقریباً پانچ منٹ میں HTTPS endpoint قائم ہو جاتا ہے، جو خودکار طور پر renew بھی ہوتا ہے۔ Control server کو plain HTTP پر چلانے کا مطلب ہے کہ ہر client کی اس کے ساتھ ہونے والی گفتگو internet پر غیر encrypted حالت میں منتقل ہوتی ہے۔