Tailnet Sendiri di VPS: Pasang Headscale sebagai Kontrol Server Tailscale

Tailscale dikenal sebagai VPN paling nyaman dipakai: login sekali, semua perangkat langsung saling melihat lewat terowongan WireGuard. Tapi ada satu bagian yang selama ini tidak pernah kita pegang sendiri: server koordinasinya. Daftar node, pembagian IP tailnet, dan distribusi kunci publik WireGuard semuanya dikelola cloud milik Tailscale. Kabar baiknya, komponen itu bisa kita pindahkan ke VPS sendiri pakai Headscale — implementasi open-source dari kontrol server Tailscale yang dirilis di bawah lisensi BSD-3-Clause.

Oke, lanjuutt.. Mari kita bahas cara pasang Headscale di VPS dari nol sampai perangkat pertama berhasil masuk tailnet.

Apa Itu Headscale dan Kenapa Cocok untuk VPS Kita

Headscale adalah self-hosted implementation dari Tailscale control server. Klien yang dipakai tetap aplikasi resmi Tailscale di semua platform — kita cuma mengarahkannya ke server sendiri, bukan ke login.tailscale.com. Untuk meng-install Headscale di VPS, beberapa hal perlu kita pahami dulu:

Cakupan sempit by design. Satu instance Headscale mengelola satu tailnet — pas untuk pemakaian pribadi atau tim kecil, bukan untuk multi-tenant raksasa.
Trafik tetap peer-to-peer. Headscale cuma jadi “buku telepon” yang mempertukarkan kunci dan mengatur routing; data kita mengalir langsung antar perangkat lewat WireGuard.
Syarat klien. Seri 0.29 Headscale mensyaratkan klien Tailscale minimal v1.80.0.

Sebagai konteks versi: Headscale 0.29.7 dirilis 30 Oktober 2026 sebagai security release yang memperbaiki temuan dari pemindai keamanan (termasuk beberapa kondisi denial of service), dan timnya menyarankan pengguna memakai Tailscale v1.104.4 atau lebih baru — perbaikan SSH forwarding dan Serve berjalan di sisi klien, jadi upgrade Headscale saja tidak cukup. Ini alasan bagus untuk mulai dari versi terbaru saat memasang.

Persiapan Sebelum Install Headscale di VPS

Headscale butuh satu syarat yang kadang terlewat: harus punya domain dan bisa diakses dari internet. Prasyaratnya singkat:

VPS Ubuntu 22.04 atau lebih baru (atau Debian 12+) dengan akses sudo.
Nama domain/subdomain yang menunjuk ke IP VPS, misalnya headscale.contohku.com. Headscale memang bisa jalan di balik reverse proxy, tapi dokumentasi resminya menyarankan instalasi langsung — jadi siapkan port 443 terbuka dan sertifikatnya nanti diurus Headscale sendiri lewat ACME.
Periksa health endpoint setelah servis jalan: https://headscale.contohku.com/health harus menjawab baik sebelum klien mendaftar.

Langkah 1: Install Paket Headscale dari Rilis Resmi

Dokumentasi resmi merekomendasikan paket .deb untuk Ubuntu/Debian karena sudah menyertakan user khusus, konfigurasi default, dan service systemd:


HEADSCALE_VERSION="0.29.7"
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 ./headscale.deb

Paket ini menaruh konfigurasi contoh di /usr/share/doc/headscale/examples/config-example.yaml — kalau butuh rujukan, salin dari sana, jangan dari branch main di GitHub yang bisa berisi perubahan yang belum dirilis.

Langkah 2: Atur config.yaml

Konfigurasi utama ada di /etc/headscale/config.yaml (Headscale juga mencarinya di $HOME/.headscale dan direktori kerja, plus bisa dipaksa lewat flag -c atau variabel HEADSCALE_CONFIG). Hal minimum yang perlu disesuaikan:


server_url: https://headscale.contohku.com
listen_addr: 0.0.0.0:8080
metrics_listen_addr: 127.0.0.1:9090

server_url — alamat publik yang akan diberitahu ke semua klien; wajib HTTPS di produksi.
listen_addr — port tempat Headscale mendengarkan koneksi gRPC dari klien.
metrics_listen_addr — port metrik Prometheus, cukup di 127.0.0.1 kalau tidak dipantau dari luar.

Setelah selesai, validasi dulu sebelum restart:


sudo headscale configtest
sudo systemctl restart headscale
sudo systemctl status headscale

Kalau configtest lolos tapi servis gagal jalan, cek ulang server_url — ini pengaturan paling sering salah ketik. Hehehe.

Langkah 3: Buat User dan Daftarkan Perangkat Pertama

Node di Headscale ditempatkan di bawah seorang user (satu user bisa punya banyak perangkat). Buat dulu:


sudo headscale users create donny
sudo headscale users list

Catatan kecil: perintah headscale butuh akses ke unix socket /var/run/headscale/headscale.sock, jadi jalankan dengan sudo, sebagai user headscale, atau masukkan user kita ke grup headscale.

Lalu, di perangkat klien (laptop, server lain, bahkan HP Android/iOS), cukup arahkan Tailscale ke server baru:


tailscale up --login-server https://headscale.contohku.com

Browser akan terbuka dan menampilkan instruksi lengkap beserta Auth ID. Di sisi VPS, setujui pendaftarannya:


sudo headscale auth register --user donny --auth-id <AUTH_ID>

Langkah 4: Preauthkey untuk Pendaftaran Non-Interaktif

Kalau ingin mendaftarkan server tanpa browser (misalnya lewat skrip provisioning), pakai pre-authenticated key:


sudo headscale preauthkeys create --user donny

Secara default kunci ini berlaku satu jam dan hanya sekali pakai — opsi lainnya bisa dilihat di headscale preauthkeys --help. Lalu di klien:


tailscale up --login-server https://headscale.contohku.com --authkey <AUTH_KEY>

Cek hasilnya dengan tailscale status — perangkat yang terdaftar akan muncul dengan IP tailnet-nya, dan tailscale ping <ip> seharusnya berhasil tanpa perlu buka satu port pun di firewall rumah/kantor.

MagicDNS: panggil perangkat dengan nama

Tanpa DNS, anggota tailnet dipanggil lewat IP — dan meskipun IP Tailscale tidak perlu dihafal, tetap tidak nyaman diketik. MagicDNS menyelesaikan ini: setiap node otomatis mendapat nama hostname.base_domain, jadi dari laptop cukup mengetik srv-web dan selesai.

Di config.yaml, bloknya ada di bagian dns:

dns:
  magic_dns: true
  base_domain: tailnet.contohku.com
  nameservers:
    global:
      - 1.1.1.1
      - 8.8.8.8

Tiga hal yang perlu diketahui:

magic_dns bawaannya sudah true — yang benar-benar wajib diisi adalah base_domain, karena tanpa itu validasi konfigurasi gagal dan Headscale menolak berjalan.
– base_domain tidak boleh sama dengan server_url, dan tidak boleh menjadi sufiksnya. Headscale menolak kombinasi itu karena MagicDNS mengambil alih domain tersebut; kalau dipaksa, justru server koordinasi dan DERP jadi tidak bisa dijangkau. Pakai dua nama terpisah: headscale.contohku.com untuk server, tailnet.contohku.com untuk MagicDNS.
– Hebatnya, Headscale punya fitur yang tidak ada di Tailscale resmi: extra_records — A/AAAA statis di dalam tailnet. Cocok untuk memberi nama pada layanan di VPS yang sama, misalnya grafana.tailnet.contohku.com, tanpa menyentuh DNS publik sama sekali.

Subnet router: ajak jaringan lokal ikut tailnet

Tailnet hanya berisi perangkat yang memasang Tailscale. Kalau ada jaringan yang anggotanya tidak bisa dipasangi klien — router rumah, kamera IP, printer — solusinya subnet router: satu node yang diizinkan meneruskan trafik ke subnet tertentu. Headscale menuntut persetujuan dua sisi, jadi langkahnya memang lebih dari satu:

1. Di node yang jadi router (VPS atau mini PC yang selalu hidup), iklankan subnet-nya:

sudo tailscale up --login-server https://headscale.contohku.com     --advertise-routes=192.168.10.0/24

Node yang sudah terdaftar tidak perlu up ulang — cukup sudo tailscale set --advertise-routes=192.168.10.0/24. Aktifkan juga IP forwarding di kernel, karena node ini sekarang meroutingkan paket milik node lain.

2. Di server Headscale, rute itu belum otomatis aktif. Lihat dulu:

sudo headscale nodes list-routes

Lalu setujui secara eksplisit:

sudo headscale nodes approve-routes --identifier 1 --routes 192.168.10.0/24

3. Di setiap klien yang ingin memakai rute tersebut:

sudo tailscale set --accept-routes

Gejala kalau langkah 2 terlewat cukup khas: list-routes menunjukkan subnet di kolom *Available* tapi kosong di *Approved*, dan klien seolah mengabaikan --accept-routes. Itu bukan bug — memang begitu desainnya.

Tiga pemeriksaan saat koneksi tidak kunjung jalan

Versi klien. Jalankan tailscale version. Seri 0.29 mensyaratkan minimal v1.80.0, dan karena 0.29.7 adalah rilis keamanan, idealnya v1.104.4 atau lebih baru — perbaikan SSH forwarding dan Serve ada di versi klien, bukan di server.
– headscale nodes list di server. Node yang tidak muncul sama sekali berarti registrasinya belum selesai — lewat web auth atau preauthkey.
– server_url. Masalah paling umum sejak dulu: salah ketik domain, atau sertifikat Lets Encrypt di balik reverse proxy belum siap saat node pertama mencoba mendaftar.

Kesimpulan

Headscale memberi kita yang selama ini jadi “kotak hitam” Tailscale: kontrol penuh atas server koordinasi, gratis, dengan klien resmi yang tetap enak dipakai. Pasang lewat paket .deb di VPS Ubuntu 22.04+, isi server_url dengan benar, buat user, lalu daftarkan perangkat lewat tailscale up --login-server. Karena 0.29.7 adalah rilis keamanan, mulai dari versi ini sekaligus memastikan klien minimal v1.80 (idealnya v1.104.4+) adalah keputusan yang tepat.

Saran penutup: mulai dari dua perangkat saja — VPS dan satu laptop — lalu rasakan dulu alurnya sebelum mengajak seluruh gadget masuk tailnet. Kalau nanti butuh dashboard berbasis browser untuk mengelola user dan node, ada proyek pendamping seperti Headplane yang bisa menyambung ke Headscale. Selamat mencoba, dan semoga tailnet pribadi pertamamu lancar jaya!