Headscale سے اپنا Tailscale سرور خود چلائیں

headscale کیا ہے

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

Control server وہ حصہ ہے جو جانتا ہے کہ network میں کون شامل ہے۔ یہ ہر node کو 100.64.0.0/10 میں سے ایک address دیتا ہے، public keys distribute کرتا ہے، اور nodes کو بتاتا ہے کہ وہ ایک دوسرے کو کہاں تلاش کریں۔ Tunnels بدستور WireGuard رہتے ہیں اور node-to-node قائم ہوتے ہیں۔ آپ کی دو machines کے درمیان traffic headscale box سے نہیں گزرتا، الا یہ کہ direct path نہ بن سکے اور nodes relay پر fallback کریں۔ Coordination کا یہ کردار خود چلانے سے یہ تبدیل ہوتا ہے کہ اسے کون رکھتا ہے، نہ کہ یہ کیا کر سکتا ہے۔ اس لیے اس تبدیلی کو بذاتِ خود security improvement سمجھنے سے پہلے اس ماڈل میں control server کیا پہنچ سکتا ہے اور کیا نہیں سمجھ لینا مفید ہے۔

Headscale ہر instance کے لیے ایک tailnet یعنی ایک Tailscale network فراہم کرتا ہے۔ project کے مطابق یہ ذاتی استعمال یا چھوٹی تنظیم کے لیے موزوں ہے۔ تین یا چار machines کے ساتھ، اپنے زیرِ انتظام VPS پر سادہ WireGuard VPN چلانا کم software کا تقاضا کرتا ہے اور اس میں خرابی کے امکانات بھی کم ہوتے ہیں۔ Headscale اس وقت مفید ثابت ہوتا ہے جب آپ ہر نئے laptop کے لیے [Peer] block دستی طور پر لکھنا نہیں چاہتے۔

اکثر لاگت ہی لوگوں کو پہلے تلاش شروع کرنے پر آمادہ کرتی ہے۔ اس لیے server چلانے کی ذمہ داری لینے سے پہلے یہ دیکھنا مفید ہے کہ hosted free plan میں حقیقتاً کیا شامل ہے، کیونکہ چند ذاتی machines عموماً اسی کے اندر آ جاتی ہیں۔ اگر آپ پہلے ہی اس حد سے آگے نکل چکے ہیں تو حساب اس لاگت کے مقابل کریں جو ہر user اور ہر tagged resource کے لیے paid plans میں آتی ہے، کیونکہ user devices کی تعداد unlimited ہے، جبکہ tagged resources کے لیے الگ allowances اور charges مقرر ہیں۔

اگر آپ self-hosted control plane چاہتے ہیں، لیکن Tailscale کے drop-in replacement کے بجائے اپنا client اور peers manage کرنے کے لیے web interface پسند کرتے ہیں، تو ایک single VPS پر NetBird قابلِ غور متبادل ہے۔ دونوں WireGuard کے ذریعے آپ کا traffic منتقل کرتے ہیں۔ اس لیے انتخاب کا انحصار اس بات پر ہوتا ہے کہ آپ access rules کیسے لکھتے ہیں اور relays کیسے کام کرتے ہیں۔ install کرنے سے پہلے ان نکات پر NetBird اور Tailscale کا تقابل کرنا مفید ہے۔ دونوں 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 چل رہا ہو۔ Headscale 0.29.6 کے لیے Tailscale client version 1.80.0 یا اس کے بعد کا version درکار ہے۔

سرکاری .deb سے headscale انسٹال کریں

پروجیکٹ اپنی .deb packages کو GitHub releases page پر شائع کرتا ہے۔ 27 اکتوبر 2026 تک تازہ ترین stable release 0.29.6 ہے، جو 24 اکتوبر 2026 کو جاری ہوئی تھی۔ پہلے اپنا architecture چیک کریں، کیونکہ file name میں architecture شامل ہوتا ہے۔

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

یہ ordinary x86 VPS پر amd64 اور Ampere یا Graviton طرز کے plan پر arm64 دکھاتا ہے۔ نیچے دیے گئے variable میں جواب رکھیں۔

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

file name سے پہلے ./ لگانا ضروری ہے۔ اس کے بغیر apt آپ کی repositories میں headscale.deb نامی package تلاش کرتا ہے اور ناکام ہو جاتا ہے۔

package ایک headscale system user بناتا ہے، default /etc/headscale/config.yaml لکھتا ہے، systemd unit انسٹال کرتا ہے، اور پھر service شروع کرتا ہے۔ اس لیے apt واپس آنے تک headscale پہلے ہی چل رہا ہوتا ہے، اور sudo systemctl is-active headscale active دکھاتا ہے۔ تاہم fresh install پر package unit کو enable نہیں کرتا۔ لہٰذا enable کرنے تک reboot کے بعد service دوبارہ شروع نہیں ہوگی؛ نیچے دیا گیا restart step یہ کام کرتا ہے۔ service shipped configuration پر بھی چل رہی ہوتی ہے، اور وہ server_url کو http://127.0.0.1:8080 کی طرف point کرتی ہے، جس تک آپ کا کوئی client رسائی نہیں کر سکتا۔ ابھی کچھ expose نہیں ہوا، کیونکہ shipped listen_addr بھی loopback پر ہے۔ تاہم server_url set کرکے service restart کرنے تک کسی client کو join نہ کریں؛ اگلے دو steps یہی کام کرتے ہیں۔

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

/etc/headscale/config.yaml کو sudo nano /etc/headscale/config.yaml کے ذریعے edit کریں، یا sed کے ساتھ یہی تین تبدیلیاں لاگو کریں۔ اصل فائل کی ایک copy محفوظ رکھیں، کیونکہ یہ فائل طویل اور تفصیلی تبصروں پر مشتمل ہے، اور باقی 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

server_url وہ public address ہے جسے headscale registration URLs بناتے وقت استعمال کرتا ہے۔ Clients --login-server کے ساتھ configured control address استعمال کرتے ہیں، اس لیے دونوں جگہ https:// کے ساتھ ایک ہی public name استعمال کریں، 127.0.0.1 ہرگز نہیں۔ headscale کی documentation کے مطابق plain HTTP، یا 443 کے علاوہ کسی port پر HTTPS، ممکن ہے؛ لیکن production کے لیے یہ HTTPS on port 443 کی مضبوط سفارش کرتی ہے، اور اس guide کے باقی حصے میں یہی configuration فرض کی گئی ہے۔

listen_addr وہ address ہے جہاں process bind ہوتا ہے۔ اسے loopback پر رہنے دیں۔ اسی server پر موجود reverse proxy TLS (transport layer security) terminate کرتا ہے اور requests کو وہاں 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 نے create کیا اور جس کی ownership اسی کے پاس ہے، اور اس سائز کے tailnet کے لیے SQLite کافی ہے۔

headscale کو دوبارہ شروع کریں اور ثابت کریں کہ یہ چل رہا ہے

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، active پرنٹ کرتا ہے، is-enabled، enabled پرنٹ کرتا ہے، اور curl، 200 پرنٹ کرتا ہے۔ Restart وہ مرحلہ ہے جو آپ کی ترمیمات load کرتا ہے۔ headscale اپنی configuration صرف start ہوتے وقت پڑھتا ہے، اس لیے package کے ذریعے شروع کیا گیا process فراہم کردہ server_url استعمال کرتا رہتا ہے، جب تک آپ اسے restart نہ کریں۔ sudo systemctl enable --now headscale یہ کام نہیں کرتا: service پہلے ہی running ہے، اس لیے --now start سے کچھ تبدیل نہیں ہوتا اور پرانی value فعال رہتی ہے۔ Boot کے وقت start کرنا enable کی ذمہ داری ہے، اور یہ خودکار طور پر نہیں ہوتا: fresh install پر package service کو enable کیے بغیر start کرتا ہے، اس لیے اوپر کی طرح ایک بار sudo systemctl enable headscale چلائیں۔

اگر is-active، active کے علاوہ کچھ بھی print کرے، یا curl، 200 print نہ کرے، تو sudo journalctl -u headscale -n 50 --no-pager کے ذریعے journal پڑھیں۔ اس مرحلے پر failure تقریباً ہمیشہ configuration file کی وجہ سے ہوتا ہے، کیونکہ headscale socket کھولنے سے پہلے پوری file parse کرتا ہے۔ اس لیے غلط indentation یا required setting کی invalid value process کو اس سے پہلے روک دیتی ہے کہ کوئی چیز listen کرے۔ File درست کریں، پھر sudo systemctl restart headscale۔ اس کے بعد configuration میں ہر تبدیلی کے لیے یہی restart درکار ہوگا۔ Clients اس کے بعد خود دوبارہ connect ہو جاتے ہیں۔ اگر systemd units آپ کے لیے نئی ہیں تو systemd کے ذریعے اپنی services اور timers چلانا یہاں استعمال ہونے والی commands کا احاطہ کرتا ہے۔

Shell میں موجود ہونے کے دوران state files بھی check کریں:

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

دونوں lines headscale سے شروع ہوتی ہیں، جو package کے ذریعے بنایا گیا unprivileged user ہے۔ noise_private.key clients کے لیے server کی identity ہے۔ اسے محفوظ رکھیں۔ اگر آپ اسے delete کر دیں تو headscale نئی identity generate کرے گا، اور clients کو دوبارہ connect ہونے سے پہلے نئی server key حاصل کرنا ہوگی؛ موجودہ registrations database میں برقرار رہیں گی۔

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

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

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

اگر file parse ہو جائے تو validate، adapted config to JSON print کرتا ہے۔ File کے format نہ ہونے کی warning صرف ظاہری مسئلہ ہے۔ اپنے laptop سے curl -sS -o /dev/null -w '%{http_code}\\n' https://headscale.example.com/health کو بھی 200 print کرنا چاہیے۔ یہ ایک 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 اور Connection headers واضح طور پر forward کرنے ہوتے ہیں۔ headscale documentation یہ کام 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 نہیں ہو سکتے، اور موجودہ nodes دوبارہ connect ہو کر online status report نہیں کر سکتے۔ اگر آپ 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 کا control connection headscale تک پہنچاتا ہے۔ اگر آپ بعد میں embedded DERP relay فعال کریں تو اسے 3478/udp بھی درکار ہوگا، جس کی وضاحت نیچے دی گئی ہے۔ Port 80 ACME (خودکار certificate management environment) کے HTTP challenge اور HTTPS پر redirect کے لیے ہے۔ Port 80 بند ہونے کی صورت میں بھی Caddy certificate حاصل کر سکتا ہے، کیونکہ یہ port 443 پر TLS-ALPN challenge استعمال کر سکتا ہے۔ تاہم، port 80 کھلا ہو تو دونوں challenges دستیاب رہتے ہیں اور plain http:// requests کو redirect کر دیا جاتا ہے۔

Port 8080 بند رہتا ہے۔ listen_addr، 127.0.0.1:8080 ہے، اس لیے proxy loopback interface کے ذریعے headscale تک پہنچتا ہے اور firewall rule کی ضرورت نہیں ہوتی۔ UFW میں 8080 کھولنے سے کچھ بھی expose نہیں ہوگا، کیونکہ باہر سے اس port پر کوئی چیز listen نہیں کر رہی۔ اس سے کوئی فائدہ بھی حاصل نہیں ہوتا۔ یاد رکھیں کہ زیادہ تر 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 کی ملکیت ہے۔ اس کے دو نتائج ہیں۔ service بند ہونے پر کمانڈ ناکام ہو جاتی ہے، اسی لیے اس guide میں ترتیب اہم ہے، اور اس کے لیے sudo درکار ہے، جب تک کہ آپ اپنا account headscale group میں شامل نہ کر دیں۔

users list ہر name کے ساتھ ایک ID دکھاتا ہے۔ آپ کو یہ number درکار ہے، کیونکہ key کمانڈ numeric user ID لیتی ہے، name نہیں۔

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

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

اپنے پہلے کلائنٹ کو --login-server کے ساتھ منسلک کریں

جس مشین کو شامل کرنا چاہتے ہیں، اس پر:

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 حالت کے ساتھ دکھائی دیتا ہے۔

server_url سے حاصل ہونے والا public HTTPS address، --login-server کے لیے استعمال کریں۔ client اپنے control URL کے آخری slashes حذف کر دیتا ہے؛ اس لیے ایسا کوئی exact string comparison نہیں ہوتا جس کے لیے آخری slash حذف کرنا ضروری ہو۔

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

اگر --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 کیا جاتا ہے۔ اگر آپ کا مقصد internet تک جانے کے بجائے اس VPS کے پیچھے موجود private network تک رسائی حاصل کرنا ہے تو یہی approval step اس subnet کو اپنے باقی tailnet کے لیے advertise کرنے کے لیے بھی کافی ہے۔ پورے networks کو اس node کے ذریعے route کرنے کے بجائے کسی node سے ایک application publish کرنا الگ کام ہے۔ اسے کرنے کے دو طریقے serve اور funnel ہیں۔ تاہم دونوں Tailscale کے اپنے certificate اور ingress mechanisms پر انحصار کرتے ہیں، اس لیے انہیں hosted-tailnet features سمجھیں، نہ کہ ایسی سہولت جو headscale فراہم کرتا ہے۔

DERP، اور براہِ راست راستہ ناکام ہونے پر network traffic کون 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 کے ساتھ استعمال کرنے کے لیے configured آتا ہے، اس لیے control plane آپ کا اپنا رہتا ہے، جبکہ relays Tailscale کے ہوتے ہیں۔ زیادہ تر لوگوں کے لیے یہ مناسب سمجھوتا ہے۔ اگر یہ قابلِ قبول نہ ہو تو اپنا relay چلائیں۔

اپنا relay چلانے کے لیے config.yaml میں derp.server کے تحت enabled: true set کریں، فراہم کردہ ipv4: 198.51.100.1 اور ipv6: 2001:db8::1 کو اپنے relay کے public addresses سے replace کریں، یا DNS استعمال کرنے کے لیے دونوں settings remove کر دیں۔ پھر headscale restart کریں اور STUN (session traversal utilities for NAT) port کو sudo ufw allow 3478/udp کے ساتھ کھولیں۔ یہ address settings DNS پر فوقیت رکھتی ہیں، اس لیے کسی ایک placeholder کو بھی برقرار رکھنے سے clients ایک ناقابلِ رسائی address پر بھیجے جائیں گے۔ Configuration file یہ requirement واضح طور پر بیان کرتی ہے: server_url میں https استعمال ہونا چاہیے، کیونکہ DERP کو TLS درکار ہے۔ derp.urls list کو خالی کرنے سے Tailscale کے relays map سے remove ہو جاتے ہیں؛ ایسا کرنے سے پہلے embedded یا custom relay کے کام کرنے کی تصدیق کریں۔ Headscale خالی relay map کے ساتھ start ہونے سے انکار کرتا ہے، اور اگر map میں صرف ایک ناقابلِ رسائی relay ہو تو وہ nodes جو براہِ راست connect نہیں ہو سکتے، آپس میں communicate نہیں کر پائیں گے۔

Client سے tailscale netcheck ہر اس relay region کی latency دکھاتا ہے جس کے بارے میں اسے معلومات ہوں، جبکہ tailscale status active peer connections کے لیے direct کو address کے ساتھ یا relay کو region code کے ساتھ دکھاتا ہے۔ relay پر stuck peer کے لیے اس کا direct path check کریں، جس میں NAT اور firewall rules بھی شامل ہیں۔ جو peer direct ہو اور پھر بھی slow ہو، اس کا مسئلہ مختلف ہے؛ وہاں عام جواب tunnel کے بجائے MTU ہوتا ہے۔

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

Proxy upgrade کو drop کر رہا ہے۔ اس کی علامت یہ ہے کہ /health، 200 واپس کرتا ہے، جبکہ نئی registrations ناکام رہتی ہیں یا موجودہ نوڈ دوبارہ connect نہیں کر پاتے۔ Control connection، Upgrade: tailscale-control-protocol لے جانے والی POST ہے، اور جو proxy اسے forward نہیں کرتا وہ registration اور node state رپورٹ کرنے والے channel، دونوں کو روک دیتا ہے۔ اپنی nginx configuration کا اوپر دی گئی upgrade lines سے موازنہ کریں، یا proxy کو مسئلے کی وجہ سے خارج کرنے کے لیے Caddy استعمال کریں۔

Public control address تبدیل ہو گیا ہے۔ نوڈز، --login-server کے ساتھ configured address پر dialing جاری رکھتے ہیں؛ server_url تبدیل کرنے سے client setting update نہیں ہوتی۔ اگر پرانا address اب آپ کے server تک نہیں پہنچتا تو ہر نوڈ پر sudo tailscale up --login-server https://headscale.example.com --force-reauth چلائیں۔

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

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

Testing کے دوران server side monitor کرنے کے لیے VPS پر sudo journalctl -u headscale -f چلائیں اور client پر tailscaled restart کریں۔ Client journal بھی check کریں: headscale تک پہنچنے والی request کے نتیجے میں default log level پر کوئی line درج ہونے کی ضمانت نہیں ہوتی، اس لیے صرف server logs خاموش ہونے سے DNS، firewall یا proxy failure ثابت نہیں ہوتا۔

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

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

Preauth keys کو جان بوجھ کر مختصر مدت کے لیے جاری کیا جاتا ہے۔ ڈیفالٹ مدت one hour اور one use ہے۔ اگر tailscale up کلید قبول نہ کرے تو client پر کچھ تبدیل کرنے کے بجائے server پر نئی کلید بنائیں۔

Node keys طویل مدت تک مؤثر رہنے والا حصہ ہیں۔ config.yaml کا node section expiry: 0 متعین کرتا ہے، اور 0 کا مطلب ہے کہ کوئی default expiry نہیں ہے؛ تاہم client کی مقرر کردہ expiry یا OIDC expiry پھر بھی لاگو ہو سکتی ہے۔ Tagged nodes خودکار expiry سے مستثنیٰ ہوتے ہیں، لیکن administrator انہیں صراحتاً expire کر سکتا ہے۔ اگر آپ non-tagged registrations کے لیے 180-day default چاہتے ہیں تو expiry: 180d متعین کریں، لیکن client کی درخواست کردہ expiry کو ترجیح حاصل ہوتی ہے اور OIDC default کو override کر سکتا ہے۔ اس setting کو تبدیل کرنے سے موجودہ registrations کی میعاد سابقہ طور پر تبدیل نہیں ہوتی۔ جس node کی expiry ہو اسے اس deadline سے پہلے sudo tailscale up --login-server https://headscale.example.com --force-reauth استعمال کرتے ہوئے دوبارہ authentication کرنا ضروری ہے؛ بصورت دیگر headless server کو دوبارہ authenticate نہ کرنے پر اس کی registration expire ہوتے ہی وہ 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 مل کر پورا server بنتے ہیں۔ انہیں 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 اور ہر registration شامل ہوتی ہے، اس لیے انہیں خود server جتنی احتیاط سے محفوظ کریں۔ VPS سے restic backups میں یہ کام schedule کے مطابق اور encrypted طریقے سے کرنے کی وضاحت ہے۔

اپ گریڈز میں install کا عمل دہرایا جاتا ہے: نیا .deb اور sudo apt install ./headscale.deb download کریں، پھر restart کریں اور is-active اور /health checks دوبارہ چلائیں۔ 0.29 سے upgrade path سخت ہے۔ minor version چھوڑ کر آگے بڑھنا blocked ہے، اور پرانے minor version پر downgrade کرنا بھی blocked ہے۔ ایک وقت میں صرف ایک minor version آگے بڑھیں، ہر step سے پہلے backup لیں، اور پہلے اس version کی release notes پڑھیں، کیونکہ اسی release میں ACL policy کے رویے میں تبدیلی کی گئی اور کئی configuration keys منتقل کی گئیں۔ Version 0.29.6 میں certificate validation اور dependencies کے لیے security updates بھی شامل ہیں، اس لیے موجودہ 0.29 installations کو یہ patch release انسٹال کرنا چاہیے۔

FAQ

کیا .deb انسٹال کرنے کے فوراً بعد headscale پہلے سے چل رہا ہوتا ہے؟

جی ہاں۔ پیکیج انسٹال ہوتے ہی سروس شروع کر دیتا ہے، فراہم کردہ /etc/headscale/config.yaml پر، جو صرف loopback پر listening کرتی ہے اور server_url کو http://127.0.0.1:8080 پر set کرتی ہے۔ نئی انسٹالیشن میں سروس enable نہیں ہوتی، اس لیے sudo systemctl enable headscale چلانے تک یہ boot کے وقت شروع نہیں ہوگی۔ فراہم کردہ address clients کے لیے بے کار ہے، اس لیے server_url، listen_addr اور base_domain میں ترمیم کریں، پھر sudo systemctl restart headscale چلائیں اور sudo systemctl is-active headscale سے تصدیق کریں۔ یہ restart ہونا ضروری ہے: headscale فائل کو صرف start کے وقت پڑھتا ہے، اور پہلے سے چل رہی سروس پر enable --now اسے boot کے لیے enable کرتا ہے لیکن restart نہیں کرتا، اس لیے پرانی values فعال رہتی ہیں۔ اگر restart کے بعد یہ fail ہو جائے تو sudo journalctl -u headscale -n 50 --no-pager مسئلے کی نشاندہی کرتا ہے۔ اس مرحلے پر وجہ تقریباً ہمیشہ YAML error ہوتی ہے، کیونکہ headscale port bind کرنے سے پہلے پوری فائل parse کرتا ہے۔

کیا میں اپنی مشینوں پر عام Tailscale client پھر بھی انسٹال کروں؟

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

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

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

رجسٹر ہونے کے بعد میرا node offline کیوں رہتا ہے؟

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

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

اس setup کے لیے ہاں: domain name اور HTTPS استعمال کریں۔ Certificates bare IP addresses کو بھی cover کر سکتے ہیں، لیکن configuration file واضح کرتی ہے کہ DERP کے لیے TLS ضروری ہے۔ Domain اور Caddy کے ساتھ تقریباً پانچ منٹ میں HTTPS endpoint تیار ہو جاتا ہے اور اس کے certificates خود renew ہوتے رہتے ہیں۔ Plain HTTP ممکن ہے، لیکن headscale کی documentation production کے لیے port 443 پر HTTPS کی پُرزور سفارش کرتی ہے اور یہ بھی بتاتی ہے کہ بعض حالات میں Tailscale client port 443 پر HTTPS فرض کرتا ہے۔