Cara Self-Host Tailscale dengan Headscale di VPS

Apa itu headscale

Headscale adalah implementasi self-hosted dari server kontrol Tailscale. Dengan demikian, mesin yang mengoordinasikan jaringan privat Anda adalah VPS milik Anda sendiri. Headscale merupakan proyek komunitas dan tidak dikelola oleh Tailscale Inc. Setiap mesin tetap menjalankan client resmi tailscale yang diarahkan ke server Anda menggunakan satu flag, --login-server.

Server kontrol adalah komponen yang mengetahui siapa saja yang termasuk dalam jaringan. Server ini memberikan setiap node sebuah alamat dari 100.64.0.0/10, mendistribusikan public key, dan memberi tahu node lokasi node lain. Tunnel tetap menggunakan WireGuard dan dibangun secara langsung antarnode. Trafik antara dua mesin Anda tidak melewati server headscale, kecuali jalur langsung tidak dapat dibuat dan node beralih ke relay. Menjalankan sendiri fungsi koordinasi tersebut mengubah pihak yang mengelolanya, bukan kemampuannya. Karena itu, pahami apa yang dapat dan tidak dapat diakses oleh server kontrol dalam model ini sebelum menganggap perpindahan ini sebagai peningkatan keamanan dengan sendirinya.

Headscale menyediakan satu tailnet (satu jaringan Tailscale) per instance. Proyek ini menyebutnya cocok untuk penggunaan pribadi atau organisasi kecil. Jika hanya ada tiga atau empat mesin, VPN WireGuard biasa pada VPS milik Anda memerlukan lebih sedikit perangkat lunak untuk dijalankan dan lebih sedikit komponen yang dapat bermasalah. Headscale mulai bermanfaat ketika Anda tidak lagi ingin menulis blok [Peer] secara manual untuk setiap laptop baru. Biaya sering menjadi alasan orang mulai mencari solusi ini. Karena itu, baca cakupan sebenarnya dari paket gratis hosted sebelum menyiapkan server, karena beberapa mesin pribadi biasanya masih tercakup di dalamnya. Jika Anda sudah melewati batas tersebut, hitung biayanya berdasarkan biaya paket berbayar per pengguna dan per resource bertag, karena perangkat pengguna tidak dibatasi, sedangkan resource bertag memiliki kuota dan biaya terpisah. Jika Anda menginginkan control plane self-hosted, tetapi lebih memilih client milik Anda sendiri dan antarmuka web untuk mengelola peer daripada pengganti langsung Tailscale, NetBird pada satu VPS merupakan alternatif yang patut dipertimbangkan. Keduanya meneruskan trafik Anda melalui WireGuard. Karena itu, pilihan bergantung pada cara Anda menulis aturan akses dan perilaku relay. Sebelum memasang salah satunya, baca perbandingan NetBird dan Tailscale dalam hal tersebut. Untuk perbandingan yang lebih luas antara kedua model ini, lihat perbedaan WireGuard dan Tailscale.

Hal yang diperlukan sebelum instalasi

• VPS yang menjalankan Ubuntu 24.04 dengan alamat IPv4 publik dan akses sudo. Jika server masih baru, ikuti sepuluh menit pertama pada VPS baru terlebih dahulu.
• DNS A record yang mengarah ke alamat tersebut. Panduan ini menggunakan headscale.example.com.
• Domain atau subdomain kedua untuk MagicDNS. Panduan ini menggunakan tailnet.example.net. Domain atau subdomain ini tidak boleh sama dengan domain pada server_url.
• Satu mesin klien untuk bergabung, yang menjalankan Linux, macOS, Windows, Android, atau iOS. Headscale 0.29.6 memerlukan versi klien Tailscale 1.80.0 atau yang lebih baru.

Instal headscale dari .deb resmi

Proyek ini menerbitkan paket .deb pada halaman releases GitHub. Per 27 Oktober 2026, rilis stabil terbaru adalah 0.29.6, yang diterbitkan pada 24 Oktober 2026. Periksa arsitektur Anda terlebih dahulu karena nama file memuat informasi tersebut.

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

Perintah tersebut menampilkan amd64 pada VPS x86 biasa dan arm64 pada paket bergaya Ampere atau Graviton. Masukkan hasilnya ke dalam variabel di bawah ini.

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

./ di depan nama file wajib disertakan. Tanpa awalan tersebut, apt akan mencari paket bernama headscale.deb di repositori Anda dan gagal.

Paket ini membuat pengguna sistem headscale, menulis /etc/headscale/config.yaml default, memasang unit systemd, lalu menjalankan service. Jadi, headscale sudah berjalan ketika apt selesai dijalankan, dan sudo systemctl is-active headscale menampilkan active. Namun, pada instalasi baru paket ini tidak mengaktifkan unit tersebut. Service tidak akan berjalan kembali setelah reboot sampai Anda mengaktifkannya, dan langkah restart di bawah ini melakukan hal tersebut. Service juga berjalan dengan konfigurasi bawaan paket, yang mengarahkan server_url ke http://127.0.0.1:8080. Alamat tersebut tidak dapat dijangkau oleh client mana pun milik Anda. Belum ada yang terekspos karena listen_addr bawaan paket juga menggunakan loopback. Namun, jangan hubungkan client apa pun sampai Anda menetapkan server_url dan me-restart service, seperti yang dilakukan oleh dua langkah berikutnya.

Konfigurasikan server_url sebelum ada klien yang bergabung

Edit /etc/headscale/config.yaml dengan sudo nano /etc/headscale/config.yaml, atau terapkan tiga perubahan yang sama dengan sed. Simpan salinan file asli karena file tersebut panjang dan memiliki banyak komentar. File itu merupakan referensi terbaik untuk pengaturan lainnya.

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 adalah alamat publik yang digunakan headscale saat membuat URL pendaftaran. Klien menggunakan alamat kontrol yang dikonfigurasikan dengan --login-server. Karena itu, gunakan nama publik yang sama dengan https:// di kedua tempat, bukan 127.0.0.1. Dokumentasi headscale menyatakan bahwa HTTP biasa, atau HTTPS pada port selain 443, dapat digunakan. Namun, dokumentasi tersebut sangat menyarankan HTTPS pada port 443 untuk produksi, dan panduan ini menggunakan konfigurasi tersebut.

listen_addr adalah alamat tempat proses melakukan binding. Biarkan pada loopback. Reverse proxy pada server yang sama melakukan terminasi TLS (transport layer security) dan meneruskan koneksi ke alamat tersebut. Dengan demikian, tidak ada perangkat di luar server yang perlu mengakses port 8080.

base_domain adalah sufiks MagicDNS, yaitu domain yang digunakan untuk nama node Anda. Sufiks ini harus berupa fully qualified domain name tanpa titik di akhir. Sufiks ini juga harus berbeda dari domain pada server_url karena kedua namespace tersebut akan bertabrakan jika tidak.

Biarkan bagian database apa adanya. Konfigurasi default menggunakan SQLite pada /var/lib/headscale/db.sqlite, di dalam direktori yang dibuat dan dimiliki oleh package. SQLite sudah memadai untuk tailnet sebesar ini.

Mulai ulang headscale dan buktikan bahwa layanan berjalan

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 menampilkan active, is-enabled menampilkan enabled, dan curl menampilkan 200. Restart adalah langkah yang memuat perubahan Anda. Headscale membaca konfigurasinya satu kali saat mulai, sehingga proses yang dimulai oleh paket tetap menggunakan server_url bawaan sampai Anda melakukan restart. sudo systemctl enable --now headscale tidak menjalankan tugas ini: service sudah berjalan, sehingga --now tidak mengubah apa pun dan nilai lama tetap aktif. Memulai service saat boot adalah tugas enable, dan hal ini tidak dilakukan secara otomatis: pada instalasi baru, paket memulai service tanpa mengaktifkannya, jadi jalankan sudo systemctl enable headscale satu kali seperti di atas.

Jika is-active menampilkan apa pun selain active, atau curl tidak menampilkan 200, baca journal dengan sudo journalctl -u headscale -n 50 --no-pager. Kegagalan pada tahap ini hampir selalu disebabkan oleh file konfigurasi, karena headscale mengurai seluruh file sebelum membuka socket. Indentasi yang salah atau pengaturan wajib yang tidak valid menghentikan proses sebelum ada proses yang listen. Perbaiki file tersebut, lalu sudo systemctl restart headscale. Setiap perubahan konfigurasi berikutnya memerlukan restart yang sama. Client akan tersambung kembali secara otomatis setelahnya. Jika unit systemd masih baru bagi Anda, menjalankan service dan timer sendiri dengan systemd membahas perintah yang digunakan di sini.

Periksa file status saat Anda masih berada di shell:

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

Kedua baris diawali headscale, yaitu user tanpa hak istimewa yang dibuat oleh paket. noise_private.key adalah identitas server bagi client-nya. Pertahankan file tersebut. Jika Anda menghapusnya, headscale akan membuat identitas baru dan client harus mengambil key server yang baru sebelum tersambung kembali; registrasi yang sudah ada tetap berada di database.

Pasang TLS di depan headscale

Client harus mengakses server_url melalui HTTPS. Caddy adalah cara paling singkat karena dapat meminta dan memperbarui sertifikat secara mandiri.

sudo apt install -y caddy

Ganti /etc/caddy/Caddyfile dengan blok dari dokumentasi 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 menampilkan adapted config to JSON jika file berhasil diuraikan. Peringatan bahwa file belum diformat hanya bersifat kosmetik. Dari laptop Anda, curl -sS -o /dev/null -w '%{http_code}\\n' https://headscale.example.com/health juga seharusnya menampilkan 200. Pemeriksaan tunggal ini membuktikan bahwa DNS, firewall, sertifikat, dan proxy bekerja bersama dengan benar.

Berikut detail proxy yang sering menghabiskan waktu. Koneksi kontrol Tailscale adalah upgrade HTTP. Koneksi ini dimulai dengan POST, bukan GET, dan nilai header Upgrade adalah tailscale-control-protocol. Caddy meneruskannya tanpa konfigurasi tambahan. nginx tidak melakukan hal tersebut. Karena itu, front end nginx harus meneruskan header Upgrade dan Connection secara eksplisit. Dokumentasi headscale melakukannya dengan 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;
    }
}

Jika baris tersebut dihilangkan, permintaan biasa tetap berhasil. Karena itu, /health mengembalikan 200 dan semuanya terlihat normal, tetapi koneksi kontrol tidak pernah terbentuk. Node baru tidak dapat melakukan registrasi, sedangkan node yang sudah ada tidak dapat tersambung kembali dan melaporkan status online. Jika Anda memilih nginx, Certbot di Ubuntu 24.04 dengan nginx membahas bagian sertifikat.

Port yang harus dibuka di UFW

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

Port 443 membawa koneksi kontrol setiap klien ke headscale. Jika Anda mengaktifkan relay DERP tertanam nanti, relay tersebut juga memerlukan 3478/udp, yang dibahas di bawah. Port 80 digunakan untuk tantangan HTTP ACME (automatic certificate management environment) dan pengalihan ke HTTPS. Caddy tetap dapat memperoleh sertifikat saat port 80 ditutup karena dapat menggunakan tantangan TLS-ALPN pada port 443. Namun, jika port 80 dibuka, kedua jenis tantangan tersedia dan permintaan http:// biasa dialihkan.

Port 8080 tetap ditutup. listen_addr adalah 127.0.0.1:8080, sehingga proxy mengakses headscale melalui antarmuka loopback dan tidak memerlukan aturan firewall. Membuka port 8080 di UFW tidak akan mengekspos apa pun karena tidak ada layanan yang mendengarkan koneksi eksternal pada port tersebut. Tindakan itu juga tidak memberikan manfaat. Perlu diingat bahwa sebagian besar provider menjalankan firewall kedua melalui panel kontrol mereka, terpisah dari UFW. Karena itu, port dapat terbuka di server tetapi tetap tertutup di edge. Dasar-dasar firewall UFW pada VPS menjelaskan sintaks aturan secara lebih terperinci.

Buat pengguna dan preauth key

sudo headscale users create alice
sudo headscale users list

Perintah headscale adalah client. Perintah ini berkomunikasi dengan daemon yang sedang berjalan melalui unix socket di /var/run/headscale/headscale.sock, yang memiliki mode 0770 dan dimiliki oleh group headscale. Ada dua konsekuensinya. Perintah ini gagal jika service dihentikan. Ini adalah alasan lain mengapa urutan dalam panduan ini penting. Perintah ini juga memerlukan sudo, kecuali Anda menambahkan akun sendiri ke group headscale.

users list mencetak ID di samping setiap nama. Anda memerlukan nomor tersebut karena perintah key menerima ID pengguna numerik, bukan nama.

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

Key hanya dicetak satu kali. Salin sekarang. Preauth key hanya dapat digunakan satu kali dan berlaku selama satu jam, kecuali Anda menentukan opsi lain. Karena itu, --expiration 24h sebaiknya ditetapkan saat Anda masih melakukan pengujian. Tambahkan --reusable untuk key yang mendaftarkan beberapa mesin. Perlakukan key tersebut seperti password karena siapa pun yang memilikinya dapat bergabung ke jaringan Anda.

Hubungkan klien pertama dengan --login-server

Pada mesin yang ingin Anda gabungkan:

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 menampilkan alamat yang ditetapkan headscale, misalnya 100.64.0.1. Kembali ke server, sudo headscale nodes list menampilkan node beserta ID, user, dan status online-nya.

Gunakan alamat HTTPS publik dari server_url untuk --login-server. Klien menghapus garis miring di akhir URL kontrolnya. Tidak ada perbandingan string yang mengharuskan Anda menghilangkan garis miring tersebut.

Mesin yang sebelumnya login ke layanan hosted Tailscale tetap menggunakan login tersebut. Jalankan sudo tailscale logout terlebih dahulu di mesin itu, lalu jalankan tailscale up dengan --login-server.

Jika Anda tidak menyertakan --auth-key, klien akan menampilkan URL. Buka URL tersebut. Halamannya menampilkan identifier untuk percobaan pendaftaran tersebut, yang kemudian Anda setujui di server:

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

Formulir ini lebih praktis untuk laptop pribadi. Preauth key lebih sesuai untuk proses yang diotomatisasi karena tidak memerlukan pengawasan manusia. Setelah VPS itu sendiri menjadi node, VPS juga dapat membawa trafik internet dari mesin Anda yang lain. Konfigurasinya adalah setup exit node, dengan satu perbedaan: Anda menyetujui route yang diiklankan di server menggunakan perintah headscale, bukan melalui konsol admin hosted. Jika yang Anda perlukan adalah akses ke jaringan privat di belakang VPS tersebut, bukan jalur keluar ke internet, langkah persetujuan yang sama berlaku untuk mengiklankan subnet tersebut ke tailnet lainnya. Mempublikasikan satu aplikasi dari sebuah node, alih-alih merutekan seluruh jaringan melaluinya, merupakan tugas yang berbeda. serve dan funnel adalah dua cara untuk melakukannya, tetapi keduanya bergantung pada machinery sertifikat dan ingress milik Tailscale. Karena itu, anggap keduanya sebagai fitur hosted-tailnet, bukan fitur yang disediakan langsung oleh headscale.

DERP dan komponen yang meneruskan trafik ketika jalur langsung gagal

DERP (designated encrypted relay for packets) adalah jalur cadangan. Jika dua node tidak dapat membuka koneksi WireGuard langsung, biasanya karena keduanya berada di balik NAT (network address translation) yang ketat, keduanya akan mengirim paket melalui relay. Relay tidak menyimpan key, sehingga tidak dapat membaca trafik Anda. Namun, relay dapat melihat node mana yang berkomunikasi dan jumlah data yang dipindahkan.

Pahami dengan jelas fungsi konfigurasi default. Headscale dikirim dengan konfigurasi yang menunjuk ke https://controlplane.tailscale.com/derpmap/default menggunakan auto_update_enabled: true dan update_frequency: 3h. Dengan demikian, control plane berada di bawah kendali Anda, sedangkan relay dikelola oleh Tailscale. Bagi kebanyakan pengguna, ini merupakan kompromi yang wajar. Jika tidak, jalankan relay sendiri.

Untuk menjalankan relay sendiri, tetapkan enabled: true di bawah derp.server dalam config.yaml. Ganti ipv4: 198.51.100.1 dan ipv6: 2001:db8::1 yang disertakan dengan alamat publik relay Anda, atau hapus kedua pengaturan tersebut untuk menggunakan DNS. Setelah itu, restart headscale dan buka port STUN (session traversal utilities for NAT) dengan sudo ufw allow 3478/udp. Pengaturan alamat tersebut mengesampingkan DNS. Jika salah satu placeholder masih ada, klien akan diarahkan ke alamat yang tidak dapat dijangkau. File konfigurasi menyatakan persyaratan ini dengan jelas: server_url harus menggunakan https karena DERP memerlukan TLS. Mengosongkan daftar derp.urls akan menghapus relay Tailscale dari map. Pastikan relay embedded atau relay kustom yang berfungsi tersedia sebelum melakukannya. Headscale menolak untuk start jika map relay kosong. Map yang hanya berisi relay yang tidak dapat dijangkau membuat node yang tidak dapat terhubung langsung juga tidak dapat berkomunikasi.

Dari sisi klien, tailscale netcheck menampilkan latensi ke setiap region relay yang dikenalnya. tailscale status menampilkan direct beserta alamat atau relay beserta kode region untuk koneksi peer yang aktif. Peer yang tetap berada pada relay memerlukan pemeriksaan jalur langsung, termasuk aturan NAT dan firewall. Peer yang berada pada direct tetapi tetap lambat merupakan masalah yang berbeda. Jawaban yang biasanya berlaku adalah MTU, bukan tunnel itu sendiri.

Mengapa node ditampilkan sebagai offline?

Proxy membuang upgrade. Tanda-tandanya adalah /health mengembalikan 200, sementara pendaftaran baru gagal atau node yang sudah ada tidak dapat terhubung kembali. Koneksi kontrol berupa POST yang membawa Upgrade: tailscale-control-protocol. Proxy yang tidak meneruskannya akan memblokir pendaftaran dan kanal yang melaporkan status node. Bandingkan konfigurasi nginx Anda dengan baris upgrade di atas, atau gunakan Caddy untuk memastikan proxy bukan penyebabnya.

Alamat kontrol publik berubah. Node terus mencoba terhubung ke alamat yang dikonfigurasi dengan --login-server. Mengubah server_url tidak memperbarui pengaturan pada client tersebut. Jika alamat lama tidak lagi mengarah ke server Anda, jalankan sudo tailscale up --login-server https://headscale.example.com --force-reauth pada setiap node.

Client tidak berjalan. Pada node, sudo systemctl is-active tailscaled dan sudo journalctl -u tailscaled -n 50 --no-pager. Client yang tidak dapat me-resolve atau menjangkau domain Anda akan mencatat percobaan ulangnya di sana.

Key kedaluwarsa. Dibahas pada bagian berikutnya.

Untuk memantau sisi server saat melakukan pengujian, jalankan sudo journalctl -u headscale -f pada VPS dan restart tailscaled pada client. Periksa journal client juga. Request yang mencapai headscale belum tentu menghasilkan baris log pada level log default. Jadi, tidak adanya log pada server saja tidak membuktikan bahwa terjadi kegagalan DNS, firewall, atau proxy.

Masa berlaku key dan node yang berhenti bekerja beberapa minggu kemudian

Ada dua masa berlaku yang terpisah. Kekeliruan antara keduanya membuang waktu.

Preauth key memang dirancang untuk cepat kedaluwarsa. Nilai default-nya adalah satu jam dan satu kali penggunaan. Jika tailscale up menolak key tersebut, buat key baru di server, bukan mengedit apa pun pada client.

Node key adalah bagian yang berlaku lebih lama. Bagian node dari config.yaml menetapkan expiry: 0, dan 0 berarti tidak ada masa berlaku default; masa berlaku client yang ditentukan secara eksplisit atau masa berlaku OIDC tetap dapat berlaku. Node bertag dikecualikan dari kedaluwarsa otomatis, tetapi administrator tetap dapat membuatnya kedaluwarsa secara eksplisit. Tetapkan expiry: 180d jika Anda ingin masa berlaku default 180 hari untuk registrasi yang tidak bertag, tetapi masa berlaku yang diminta client memiliki prioritas dan OIDC dapat menggantikan nilai default. Perubahan pada pengaturan ini tidak mengubah registrasi yang sudah ada secara retroaktif. Node yang memiliki masa berlaku harus melakukan autentikasi ulang sebelum batas waktu tersebut menggunakan sudo tailscale up --login-server https://headscale.example.com --force-reauth. Server headless yang tidak pernah diautentikasi ulang akan terputus dari jaringan ketika registrasinya kedaluwarsa.

Lakukan secara manual jika seseorang kehilangan laptop. sudo headscale nodes list menampilkan ID node, lalu sudo headscale nodes expire -i 3 mengeluarkan node tersebut, dan sudo headscale nodes delete -i 3 menghapusnya sepenuhnya dari jaringan.

Pencadangan dan pemutakhiran

/var/lib/headscale dan /etc/headscale secara bersama-sama mencakup seluruh server. Hentikan service sebelum menyalinnya, karena SQLite mungkin sedang memproses operasi tulis dan database yang disalin saat sedang digunakan dapat menjadi tidak konsisten.

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

Pindahkan kedua file tersebut keluar dari server. File-file itu berisi private key dan seluruh data registrasi, sehingga harus dilindungi dengan tingkat kehati-hatian yang sama seperti server itu sendiri. pencadangan restic dari VPS membahas cara menjadwalkan proses ini dan mengenkripsinya.

Pemutakhiran mengulangi proses instalasi: unduh .deb dan sudo apt install ./headscale.deb yang baru, lalu restart dan jalankan kembali pemeriksaan is-active dan /health. Sejak versi 0.29, jalur pemutakhiran menerapkan aturan yang ketat. Melewati versi minor akan diblokir, begitu pula menurunkan versi ke versi minor yang lebih lama. Pindahkan versi minor satu per satu, buat backup sebelum setiap langkah, dan baca catatan rilis versi tersebut terlebih dahulu karena rilis yang sama mengubah perilaku kebijakan ACL dan memindahkan beberapa kunci konfigurasi. Version 0.29.6 juga mencakup pembaruan keamanan untuk validasi sertifikat dan dependensi, sehingga instalasi 0.29 yang sudah ada sebaiknya dip#### diperbarui ke patch release ini.

FAQ

Apakah headscale sudah berjalan segera setelah saya menginstal .deb?

Ya. Paket tersebut memulai service segera setelah instalasi, pada /etc/headscale/config.yaml bawaan paket, yang hanya listen pada loopback dan menetapkan server_url ke http://127.0.0.1:8080. Pada instalasi baru, paket tidak mengaktifkan service, sehingga service tidak akan start saat boot sampai Anda menjalankan sudo systemctl enable headscale. Alamat bawaan tersebut tidak berguna bagi client, jadi edit server_url, listen_addr, dan base_domain, lalu jalankan sudo systemctl restart headscale dan konfirmasikan dengan sudo systemctl is-active headscale. Nilainya harus restart: headscale hanya membaca file saat start, sedangkan enable --now pada service yang sudah berjalan mengaktifkannya saat boot tetapi tidak me-restart service, sehingga nilai lama tetap aktif. Jika service gagal setelah restart, sudo journalctl -u headscale -n 50 --no-pager menunjukkan masalahnya. Pada tahap ini, penyebabnya hampir selalu error YAML karena headscale mem-parsing seluruh file sebelum listen pada sebuah port.

Apakah saya tetap perlu menginstal client Tailscale biasa pada mesin saya?

Ya. Headscale hanya menggantikan control server. Setiap node menjalankan client resmi dari Tailscale, dan Anda mengarahkannya ke server dengan sudo tailscale up --login-server https://headscale.example.com. Flag tersebut tersedia pada client standar, jadi tidak ada yang perlu di-patch atau di-build ulang.

Apakah trafik saya melewati server headscale?

Biasanya tidak. Headscale mengoordinasikan jaringan serta membagikan key dan alamat, sedangkan jalur data menggunakan WireGuard secara langsung antara node Anda. Trafik hanya mengambil jalur memutar ketika dua node tidak dapat saling menjangkau secara langsung dan beralih ke relay DERP. Dengan konfigurasi bawaan, relay tersebut adalah relay publik milik Tailscale. Jalankan tailscale status pada sebuah node untuk melihat apakah peer tertentu berstatus direct atau berada pada relay.

Mengapa node saya tetap offline setelah melakukan registrasi?

Node yang muncul di headscale nodes list tetapi tidak pernah online memerlukan pemeriksaan koneksi control-nya, termasuk reverse proxy. Koneksi tersebut adalah HTTP upgrade yang dikirim sebagai POST dengan header Upgrade: tailscale-control-protocol. nginx akan membuang koneksi itu kecuali Anda meneruskan header Upgrade dan Connection secara eksplisit dengan proxy_set_header, yang dilakukan konfigurasi di atas melalui blok map $http_upgrade $connection_upgrade. Membuang header tersebut juga mencegah node baru melakukan registrasi. Caddy meneruskannya tanpa konfigurasi tambahan, sehingga dapat digunakan sebagai cara cepat untuk menguji apakah masalahnya ada pada proxy.

Apakah saya memerlukan nama domain dan TLS untuk headscale?

Untuk setup ini, ya: gunakan nama domain dan HTTPS. Sertifikat juga dapat mencakup alamat IP tanpa nama domain, tetapi file konfigurasi menyatakan bahwa DERP memerlukan TLS. Domain dan Caddy dapat disiapkan dalam waktu sekitar lima menit dan menyediakan endpoint HTTPS yang memperbarui sertifikat secara otomatis. HTTP biasa tetap memungkinkan, tetapi dokumentasi headscale sangat menyarankan HTTPS pada port 443 untuk production dan mencatat bahwa client Tailscale mengasumsikan HTTPS pada port 443 dalam situasi tertentu.