Kendi Headscale Sunucunuzu Kurma Rehberi

Headscale nedir

Headscale, Tailscale kontrol sunucusunun kendi kendine barındırılan (self-hosted) bir uygulamasıdır; dolayısıyla özel ağınızı koordine eden makine, sahibi olduğunuz bir VPS'tir. Bu bir topluluk projesidir ve Tailscale Inc. tarafından yönetilmez. Her makine, --login-server bayrağı ile sunucunuza yönlendirilmiş resmi tailscale istemcisini çalıştırmaya devam eder.

Kontrol sunucusu, ağa kimin dahil olduğunu bilen kısımdır. Her düğüme 100.64.0.0/10 aralığından bir adres atar, genel anahtarları dağıtır ve düğümlere birbirlerini nerede bulacaklarını söyler. Tüneller, düğümden düğüme kurulan WireGuard bağlantısı olarak kalır. İki makineniz arasındaki trafik, doğrudan bir yol oluşturulamadığı ve düğümler bir röleye (relay) başvurmak zorunda kalmadığı sürece headscale sunucusu üzerinden geçmez. Bu koordinasyon rolünü bizzat üstlenmek, sistemin yeteneklerini değil, sadece kontrolün kimde olduğunu değiştirir; bu nedenle geçişi tek başına bir güvenlik kazanımı olarak görmeden önce bu modelde bir kontrol sunucusunun nelere erişip nelere erişemeyeceğini anlamak önemlidir.

Headscale, her örnekte bir tailnet (tek bir Tailscale ağı) sunar. Proje bunu kişisel kullanım veya küçük bir kuruluş için uygun olarak tanımlar. Üç veya dört makine için sahip olduğunuz bir VPS üzerinde yalnızca WireGuard VPN çalıştırmak, yönetilmesi gereken yazılımı ve bozulabilecek bileşenleri azaltır. Her yeni dizüstü bilgisayar için bir [Peer] bloğunu elle yazmak istemediğiniz noktada Headscale avantaj sağlar. Maliyet, insanların araştırmaya başlamasının başlıca nedenlerinden biridir. Bu nedenle bir sunucu üstlenmeden önce barındırılan ücretsiz planın gerçekte neleri kapsadığını okumakta yarar vardır; çünkü birkaç kişisel makine genellikle bu planın sınırları içinde kalır. Bu sınırı zaten aştıysanız, kullanıcı ve etiketlenmiş kaynak başına ücretli planların maliyetini hesaplayarak karşılaştırın. Kullanıcı cihazları sınırsızdır; etiketlenmiş kaynaklar için ise ayrı kotalar ve ücretler uygulanır. Self-hosted bir control plane istiyor, ancak Tailscale için doğrudan bir alternatif yerine kendi istemcisi ve peer'ları yönetmek için bir web arayüzü tercih ediyorsanız, tek bir VPS üzerinde NetBird değerlendirilebilecek alternatiftir. Her ikisi de trafiğinizi WireGuard üzerinden taşır. Bu nedenle seçim, erişim kurallarını nasıl yazdığınıza ve relay'lerin nasıl davrandığına bağlıdır. Herhangi birini kurmadan önce NetBird ile Tailscale'i bu noktalar açısından karşılaştırmak yararlı olacaktır. İki modelin daha kapsamlı karşılaştırması için WireGuard ile Tailscale arasındaki farklara bakın.

Kurulum öncesi gereksinimler

• Herkese açık bir IPv4 adresi ve sudo erişimi olan, Ubuntu 24.04 yüklü bir VPS. Sunucu yeniyse, önce yeni bir VPS üzerinde ilk on dakika rehberini uygulayın.
• Bu adrese yönlendirilmiş bir DNS A kaydı. Bu rehberde headscale.example.com kullanılmaktadır.
• MagicDNS için ikinci bir alan adı veya alt alan adı. Bu rehberde tailnet.example.net kullanılmaktadır. Bu alan adı, server_url içindekiyle aynı olmamalıdır.
• Ağa dahil edilecek; Linux, macOS, Windows, Android veya iOS çalıştıran bir istemci makinesi. Headscale 0.29.6, Tailscale istemci sürümü 1.80.0 veya daha yenisini gerektirir.

Resmi .deb paketinden headscale kurulumu

Proje, GitHub releases sayfasında .deb paketlerini yayımlar. 27 Ekim 2026 itibarıyla en son kararlı sürüm 0.29.6'dır ve 24 Ekim 2026 tarihinde yayımlanmıştır. Önce mimarinizi kontrol edin; dosya adı mimari bilgisini içerir.

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

Bu komut, standart bir x86 VPS üzerinde amd64, Ampere veya Graviton türü bir planda ise arm64 çıktısını verir. Aşağıdaki değişkende yanıtı saklayın.

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

Dosya adının başındaki ./ gereklidir. Bu ifade olmadan apt, depolarınızda headscale.deb adlı bir paket arar ve başarısız olur.

Paket, headscale adlı bir sistem kullanıcısı oluşturur, varsayılan bir /etc/headscale/config.yaml dosyası yazar, bir systemd unit'i kurar ve ardından servisi başlatır. Bu nedenle apt döndüğünde headscale zaten çalışıyor olur ve sudo systemctl is-active headscale active çıktısını verir. Ancak yeni kurulumda paket unit'i enable etmez. Bu nedenle enable işlemi yapılana kadar servis yeniden başlatmanın ardından tekrar çalışmaz. Aşağıdaki restart adımı bu işlemi yapar. Servis ayrıca paketle gelen yapılandırmayla çalışır. Bu yapılandırma server_url değerini, sizin hiçbir istemcinizin erişemeyeceği http://127.0.0.1:8080 adresine yönlendirir. Henüz dışarıya açık bir şey yoktur; çünkü paketle gelen listen_addr de loopback üzerinde çalışır. Ancak server_url değerini ayarlayıp servisi yeniden başlatana kadar hiçbir istemciyi ağa dahil etmeyin. Sonraki iki adım bu işlemleri yapar.

Herhangi bir istemci katılmadan önce server_url yapılandırması

/etc/headscale/config.yaml dosyasını sudo nano /etc/headscale/config.yaml ile düzenleyin veya aynı üç değişikliği sed ile uygulayın. Dosya uzun ve yoğun açıklamalar içerdiğinden, diğer ayarlar için en iyi referans kaynağıdır; bu nedenle orijinal dosyanın bir kopyasını saklayın.

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, headscale'in kayıt URL'lerini oluştururken kullandığı genel adrestir. İstemciler, --login-server ile yapılandırılan kontrol adresini kullanır; bu nedenle her iki yerde de aynı genel ismi https:// ile kullanın, asla 127.0.0.1 kullanmayın. Headscale belgeleri düz HTTP veya 443 dışındaki bir portta HTTPS kullanımının mümkün olduğunu belirtse de, üretim ortamları için 443 numaralı portta HTTPS kullanımını şiddetle önerir ve bu kılavuzun geri kalanı bu varsayıma dayanır.

listen_addr, sürecin bağlandığı yerdir. Bunu loopback üzerinde bırakın. Aynı sunucudaki bir reverse proxy, TLS (taşıma katmanı güvenliği) sonlandırmasını yapar ve trafiği buraya iletir; bu nedenle sunucu dışındaki hiçbir şeyin 8080 numaralı porta erişmesi gerekmez.

base_domain, düğümlerinizin altında isim alacağı alan adı olan MagicDNS sonekidir. Bu, sonunda nokta olmayan tam nitelikli bir alan adı (FQDN) olmalı ve server_url içindeki alan adından farklı olmalıdır; aksi takdirde iki isim alanı çakışacaktır.

Veritabanı bölümünü değiştirmeyin. Varsayılan ayar, paketin oluşturduğu ve sahipliğini elinde bulundurduğu dizindeki /var/lib/headscale/db.sqlite konumunda bulunan SQLite'tır ve SQLite bu boyuttaki bir tailnet için yeterlidir.

Headscale'i yeniden başlatın ve çalıştığını doğrulayın

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 çıktısı active değerini, is-enabled çıktısı enabled değerini, curl ise 200 değerini gösterir. Düzenlemelerinizi yükleyen adım yeniden başlatmadır. Headscale yapılandırmasını yalnızca başlatılırken bir kez okur. Bu nedenle paket tarafından başlatılan süreç, yeniden başlatılana kadar yayımlanan server_url değerini kullanmaya devam eder. sudo systemctl enable --now headscale bu işi yapmaz: servis zaten çalıştığı için --now başlatma işlemi hiçbir şeyi değiştirmez ve eski değer etkin kalır. Açılışta başlatma işlemi enable tarafından gerçekleştirilir ve bu işlem sizin için yapılmaz: yeni bir kurulumda paket servisi başlatır ancak etkinleştirmez. Bu nedenle yukarıda olduğu gibi sudo systemctl enable headscale komutunu bir kez çalıştırın.

is-active çıktısı active dışında herhangi bir şey gösteriyorsa veya curl çıktısında 200 görünmüyorsa sudo journalctl -u headscale -n 50 --no-pager ile journal kayıtlarını okuyun. Bu aşamadaki hata neredeyse her zaman yapılandırma dosyasından kaynaklanır. Headscale bir socket açmadan önce dosyanın tamamını ayrıştırır. Bu nedenle hatalı girinti veya geçersiz bir zorunlu ayar, herhangi bir süreç port dinlemeye başlamadan önce süreci durdurur. Dosyayı düzeltin ve ardından sudo systemctl restart headscale komutunu çalıştırın. Bundan sonraki her yapılandırma değişikliği aynı yeniden başlatma işlemini gerektirir. İstemciler bundan sonra kendiliğinden yeniden bağlanır. systemd unit'leri sizin için yeniyse, systemd ile kendi servislerinizi ve timer'larınızı çalıştırma bölümünde burada kullanılan komutlar açıklanır.

Shell içindeyken durum dosyalarını kontrol edin:

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

Her iki satır da paketin oluşturduğu ayrıcalıksız kullanıcı olan headscale ile başlar. noise_private.key, sunucunun istemcilere karşı kimliğidir. Bu dosyayı koruyun. Silerseniz headscale yeni bir kimlik oluşturur ve istemcilerin yeniden bağlanmadan önce yeni sunucu anahtarını alması gerekir; mevcut kayıtlar veritabanında kalır.

headscale önüne TLS ekleme

İstemciler server_url adresine HTTPS üzerinden erişmelidir. Caddy, sertifikayı kendi başına talep edip yenilediği için en kısa yoldur.

sudo apt install -y caddy

/etc/caddy/Caddyfile içeriğini headscale dokümantasyonundaki blok ile değiştirin:

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, dosya ayrıştırıldığında adapted config to JSON çıktısını verir. Dosyanın biçimlendirilmediğine dair bir uyarı yalnızca kozmetiktir. Dizüstü bilgisayarınızdan curl -sS -o /dev/null -w '%{http_code}\\n' https://headscale.example.com/health komutu da 200 çıktısını vermelidir. Bu tek kontrol; DNS, güvenlik duvarı, sertifika ve proxy'nin birlikte çalıştığını kanıtlar.

İşte insanların bir akşamını harcamasına neden olan proxy detayı. Tailscale kontrol bağlantısı bir HTTP yükseltme (upgrade) işlemidir, GET yerine POST ile başlatılır ve Upgrade başlığının değeri tailscale-control-protocol şeklindedir. Caddy bunu ek bir yapılandırma gerektirmeden iletir. nginx bunu yapmaz, bu nedenle bir nginx ön ucu Upgrade ve Connection başlıklarını açıkça iletmelidir. headscale dokümantasyonu bunu bir yükseltme eşlemesi (upgrade map) ile yapar:

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;
    }
}

Bu satırları atlarsanız normal istekler yine de başarılı olur; bu yüzden /health komutu 200 döner ve her şey yolunda görünür, ancak kontrol bağlantısı asla kurulamaz: yeni düğümler kaydolamaz ve mevcut düğümler yeniden bağlanıp çevrimiçi olduklarını bildiremez. nginx yolunu seçerseniz, nginx ile Ubuntu 24.04 üzerinde Certbot rehberi sertifika kısmını kapsar.

UFW üzerinde açılması gereken portlar

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

443 numaralı port, her istemcinin headscale üzerindeki kontrol bağlantısını taşır. Eğer daha sonra gömülü DERP rölesini etkinleştirirseniz, aşağıda belirtilen 3478/udp portuna da ihtiyaç duyulacaktır. 80 numaralı port, ACME (otomatik sertifika yönetimi ortamı) HTTP sınaması ve HTTPS yönlendirmesi için kullanılır. Caddy, 80 numaralı port kapalıyken de TLS-ALPN sınamasını 443 numaralı port üzerinden kullanarak sertifika alabilir; ancak 80 numaralı port açık olduğunda her iki sınama yöntemi de kullanılabilir ve düz http:// istekleri yönlendirilebilir.

8080 numaralı port kapalı kalmalıdır. listen_addr, 127.0.0.1:8080 olduğu için proxy, headscale'e loopback arayüzü üzerinden erişir ve bu süreçte herhangi bir güvenlik duvarı kuralı devreye girmez. 8080 numaralı portu UFW üzerinde açmak, dışarıdan dinleyen bir servis olmadığı için herhangi bir erişim sağlamaz ve bir fayda getirmez. Çoğu sağlayıcının, UFW'den bağımsız olarak kontrol panellerinde ikinci bir güvenlik duvarı çalıştırdığını unutmayın; bu nedenle bir port sunucu üzerinde açık olsa bile ağ sınırında kapalı olabilir. VPS üzerinde UFW güvenlik duvarı temelleri, kural sözdizimini daha ayrıntılı bir şekilde ele almaktadır.

Bir kullanıcı ve preauth anahtarı oluşturma

sudo headscale users create alice
sudo headscale users list

headscale komutu bir istemcidir. /var/run/headscale/headscale.sock konumundaki unix soketi üzerinden çalışan daemon ile iletişim kurar; bu soket 0770 modundadır ve headscale grubuna aittir. Buradan iki sonuç çıkar. Servis durdurulduğunda komut başarısız olur; bu rehberdeki sıralamanın önemli olmasının diğer nedeni budur. Ayrıca kendi hesabınızı headscale grubuna eklemediğiniz sürece sudo yetkisi gerektirir.

users list, her ismin yanında bir ID yazdırır. Bu numaraya ihtiyacınız vardır, çünkü key komutu isim yerine sayısal bir kullanıcı ID'si kabul eder.

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

Anahtar yalnızca bir kez yazdırılır. Şimdi kopyalayın. Bir preauth anahtarı tek kullanımlıktır ve aksi belirtilmedikçe bir saat geçerlidir; bu nedenle test aşamasındayken --expiration 24h ayarını yapmak faydalıdır. Birden fazla makineyi kaydedecek bir anahtar için --reusable parametresini ekleyin. Bu anahtarı bir parola gibi koruyun, çünkü elinde tutan herkes ağınıza katılabilir.

İlk istemcinizi --login-server ile bağlayın

Ağa dahil etmek istediğiniz makinede:

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 tarafından atanan adresi yazdırır; bu, 100.64.0.1 gibi bir değerdir. Sunucuya geri döndüğünüzde, sudo headscale nodes list komutu düğümü kimliği, kullanıcısı ve çevrimiçi durumuyla birlikte gösterir.

--login-server için server_url adresindeki genel HTTPS adresini kullanın. İstemci, kontrol URL'sinin sonundaki eğik çizgileri (trailing slashes) kaldırır; birini çıkarmanızı gerektiren kesin bir karakter dizisi karşılaştırması yoktur.

Daha önce Tailscale'in barındırılan hizmetine giriş yapmış bir makine bu oturumu korur. Önce üzerinde sudo tailscale logout komutunu çalıştırın, ardından --login-server ile tailscale up komutunu çalıştırın.

--auth-key parametresini kullanmazsanız, istemci bunun yerine bir URL yazdırır. Bu URL'yi açtığınızda sayfa, sunucu üzerinde onaylamanız gereken kayıt denemesine ait tanımlayıcıyı gösterir:

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

Bu form kendi dizüstü bilgisayarınız için daha kullanışlıdır. Ön kimlik doğrulama anahtarları (preauth keys), herhangi bir insan müdahalesi gerektirmediğinden betikleştirilmiş işlemler için daha uygundur. VPS'in kendisi bir düğüm haline geldiğinde, diğer makinelerinizin internet trafiğini de taşıyabilir; bu çıkış düğümü kurulumu ile aynıdır, tek fark, barındırılan bir yönetici konsolu yerine sunucuda headscale komutuyla duyurulan rotayı onaylamanızdır. Eğer amacınız internete çıkış sağlamak değil de, VPS'in arkasında bulunan özel bir ağa erişmekse, aynı onay adımı bu alt ağı tailnet'inizin geri kalanına duyurmak için de geçerlidir. Bir düğüm üzerinden tüm ağları yönlendirmek yerine tek bir uygulamayı yayınlamak farklı bir işlemdir ve bunu yapmanın iki yolu serve ve funnel özellikleridir; ancak her ikisi de Tailscale'in kendi sertifika ve giriş mekanizmalarına dayandığından, bunları headscale'in size sunduğu bir özellikten ziyade barındırılan tailnet özellikleri olarak değerlendirin.

DERP ve doğrudan yol başarısız olduğunda trafiği aktaran mekanizma

DERP (designated encrypted relay for packets), yedek yol işlevi görür. İki düğüm, genellikle her ikisi de katı NAT (network address translation) arkasında olduğu için doğrudan bir WireGuard bağlantısı kuramadığında, paketlerini bir aktarıcı (relay) üzerinden gönderir. Aktarıcı hiçbir anahtara sahip değildir, bu nedenle trafiğinizi okuyamaz. Yalnızca hangi düğümlerin birbiriyle konuştuğunu ve ne kadar veri aktarıldığını görür.

Varsayılan yapılandırmanın ne yaptığı konusunda net olun. Headscale, https://controlplane.tailscale.com/derpmap/default adresine işaret edecek şekilde auto_update_enabled: true ve update_frequency: 3h ile birlikte gelir; bu sayede kontrol düzlemi size aitken aktarıcılar Tailscale'e ait olur. Çoğu kullanıcı için bu makul bir takastır. Eğer değilse, kendi aktarıcınızı çalıştırın.

Kendi aktarıcınızı çalıştırmak için config.yaml dosyasında derp.server altındaki enabled: true ayarını yapın, varsayılan ipv4: 198.51.100.1 ve ipv6: 2001:db8::1 değerlerini aktarıcınızın genel IP adresleriyle değiştirin veya DNS kullanmak için her iki ayarı da kaldırın; ardından headscale servisini yeniden başlatın ve sudo ufw allow 3478/udp ile STUN (session traversal utilities for NAT) portunu açın. Bu adres ayarları DNS'i geçersiz kılar, bu nedenle yer tutuculardan birini bile bırakmak istemcileri ulaşılamaz bir adrese yönlendirir. Yapılandırma dosyası gereksinimi açıkça belirtir: server_url mutlaka https kullanmalıdır, çünkü DERP TLS gerektirir. derp.urls listesini boşaltmak, Tailscale'in aktarıcılarını haritadan kaldırır; bunu yapmadan önce çalışan bir gömülü veya özel aktarıcınız olduğundan emin olun. Headscale, boş bir aktarıcı haritasıyla başlamayı reddeder; yalnızca ulaşılamaz bir aktarıcı içeren bir harita ise doğrudan bağlantı kuramayan düğümlerin iletişim kuramamasına neden olur.

Bir istemci üzerinden tailscale netcheck komutu, bilinen her aktarıcı bölgesine olan gecikme süresini yazdırır; tailscale status komutu ise aktif eş bağlantıları için bir adresle birlikte direct veya bir bölge koduyla birlikte relay çıktısını gösterir. relay durumunda takılı kalan bir eşin, NAT ve güvenlik duvarı kuralları dahil olmak üzere doğrudan yolunun kontrol edilmesi gerekir. direct durumunda olan ancak yine de yavaş çalışan bir eş ise farklı bir konudur ve bu durumdaki genel çözüm tünelin kendisinden ziyade MTU değeridir.

Bir düğüm neden çevrimdışı görünüyor?

Proxy, yükseltme işlemini düşürüyor. Bunun belirtisi, /health komutunun 200 döndürmesi ancak yeni kayıtların başarısız olması veya mevcut düğümlerin yeniden bağlanamamasıdır. Kontrol bağlantısı, Upgrade: tailscale-control-protocol taşıyan bir POST isteğidir; bunu iletmeyen bir proxy, hem kayıt işlemini hem de düğüm durumunu bildiren kanalı engeller. Nginx yapılandırmanızı yukarıdaki yükseltme satırlarıyla karşılaştırın veya proxy kaynaklı bir sorun olup olmadığını anlamak için Caddy'ye geçiş yapın.

Genel kontrol adresi değişti. Düğümler, --login-server ile yapılandırılan adresi aramaya devam eder; server_url değerini değiştirmek, istemci ayarını güncellemez. Eski adres artık sunucunuza ulaşmıyorsa, her düğümde sudo tailscale up --login-server https://headscale.example.com --force-reauth komutunu çalıştırın.

İstemci çalışmıyor. Düğüm üzerinde sudo systemctl is-active tailscaled ve sudo journalctl -u tailscaled -n 50 --no-pager komutlarını kullanın. Alan adınızı çözümleyemeyen veya ona ulaşamayan bir istemci, yeniden deneme kayıtlarını burada tutar.

Anahtarın süresi doldu. Bir sonraki bölümde ele alınmıştır.

Test sırasında sunucu tarafını izlemek için VPS üzerinde sudo journalctl -u headscale -f komutunu çalıştırın ve istemci üzerinde tailscaled servisini yeniden başlatın. İstemci günlüğünü de kontrol edin: headscale'e ulaşan bir istek, varsayılan günlük seviyesinde her zaman bir satır oluşturmayabilir; bu nedenle sunucu günlüğünün sessiz kalması, DNS, güvenlik duvarı veya proxy kaynaklı bir hata olduğu anlamına gelmez.

Anahtar geçerlilik süresi ve haftalar sonra çalışmayı durduran düğüm

İki ayrı geçerlilik süresi mevcuttur ve bunların karıştırılması zaman kaybına yol açar.

Preauth anahtarları tasarım gereği hızlıca geçerliliğini yitirir. Varsayılan değer bir saat ve tek kullanımdır. Eğer tailscale up anahtarı reddederse, istemci tarafında herhangi bir düzenleme yapmak yerine sunucu üzerinde yeni bir anahtar oluşturun.

Düğüm anahtarları (node keys) uzun ömürlü olan kısımdır. config.yaml dosyasının node bölümü expiry: 0 ayarını belirler; 0 değeri varsayılan bir geçerlilik süresi olmadığını ifade eder. Yine de açık bir istemci geçerlilik süresi veya OIDC geçerlilik süresi uygulanabilir. Etiketli düğümler otomatik geçerlilik süresinden muaftır, ancak bir yönetici bunları açıkça devre dışı bırakabilir. Etiketlenmemiş kayıtlar için 180 günlük bir varsayılan süre istiyorsanız expiry: 180d ayarını yapılandırın; ancak istemci tarafından talep edilen bir geçerlilik süresi önceliklidir ve OIDC varsayılan değeri geçersiz kılabilir. Bu ayarın değiştirilmesi, mevcut kayıtları geriye dönük olarak etkilemez. Geçerlilik süresi olan bir düğümün, bu süre dolmadan önce sudo tailscale up --login-server https://headscale.example.com --force-reauth kullanılarak yeniden kimlik doğrulaması yapması gerekir. Kimsenin yeniden kimlik doğrulaması yapmadığı başsız (headless) bir sunucu, kaydı sona erdiğinde ağdan düşecektir.

Birisi dizüstü bilgisayarını kaybettiğinde bu işlemi manuel olarak gerçekleştirin. sudo headscale nodes list size kimlik bilgisini verir, ardından sudo headscale nodes expire -i 3 o düğümün oturumunu kapatır ve sudo headscale nodes delete -i 3 onu ağdan tamamen kaldırır.

Yedekleme ve yükseltmeler

/var/lib/headscale ve /etc/headscale birlikte tüm sunucuyu oluşturur. Kopyalamadan önce servisi durdurun; SQLite üzerinde devam eden yazma işlemleri olabilir ve yük altındayken kopyalanan bir veritabanı tutarsız hale gelebilir.

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

Her iki dosyayı da sunucudan dışarı taşıyın. Bu dosyalar özel anahtarları ve tüm kayıtları içerdiğinden, sunucunun kendisiyle aynı özeni hak ederler. VPS üzerinden restic yedekleri bölümü, bu işlemin zamanlanmış ve şifreli bir şekilde nasıl yapılacağını açıklar.

Yükseltme işlemleri kurulumun tekrarıdır: yeni .deb ve sudo apt install ./headscale.deb dosyalarını indirin, ardından servisi yeniden başlatın ve is-active ile /health kontrollerini tekrar çalıştırın. 0.29 sürümünden itibaren yükseltme yolu katıdır. Ara sürümleri atlamak engellenmiştir; aynı şekilde daha eski bir ara sürüme düşürme işlemi de yapılamaz. Her seferinde bir ara sürüm ilerleyin, her adımdan önce yedek alın ve ilgili sürümün sürüm notlarını önceden okuyun; çünkü aynı sürüm ACL politikası davranışını değiştirmiş ve çeşitli yapılandırma anahtarlarının yerini değiştirmiştir. 0.29.6 sürümü ayrıca sertifika doğrulama ve bağımlılıklar için güvenlik güncellemeleri içerir, bu nedenle mevcut 0.29 kurulumları bu yama sürümüne geçmelidir.

FAQ

headscale, .deb kurulumundan hemen sonra zaten çalışıyor mu?

Evet. Paket, kurulum tamamlanır tamamlanmaz servisi başlatır. Bu işlem, yalnızca loopback üzerinden dinleyen ve server_url değerini http://127.0.0.1:8080 olarak ayarlayan paketle birlikte gelen /etc/headscale/config.yaml üzerinde gerçekleşir. Yeni bir kurulumda servis etkinleştirilmez. Bu nedenle sudo systemctl enable headscale komutunu çalıştırana kadar sistem açılışında başlamaz. Paketle birlikte gelen adres istemciler için kullanılamaz. Bu nedenle server_url, listen_addr ve base_domain değerlerini düzenleyin. Ardından sudo systemctl restart headscale komutunu çalıştırın ve sudo systemctl is-active headscale ile doğrulayın. Bu işlemin restart olması gerekir. headscale dosyayı yalnızca başlatılırken okur. Çalışmakta olan bir servis üzerinde enable --now kullanılması servisi sistem açılışında etkinleştirir, ancak servisi yeniden başlatmaz. Bu nedenle eski değerler kullanılmaya devam eder. Yeniden başlatma sonrasında hata oluşursa sudo journalctl -u headscale -n 50 --no-pager sorunun ne olduğunu belirtir. Bu aşamada sorun neredeyse her zaman bir YAML hatasıdır. Çünkü headscale bir portu dinlemeye başlamadan önce dosyanın tamamını ayrıştırır.

Makinelerime normal Tailscale istemcisini de kurmam gerekiyor mu?

Evet. Headscale yalnızca control server bileşeninin yerini alır. Her node, Tailscale tarafından sağlanan resmi istemciyi çalıştırır. İstemciyi sudo tailscale up --login-server https://headscale.example.com ile sunucunuza yönlendirirsiniz. Bu flag standart istemcide bulunur. Bu nedenle herhangi bir patch uygulamak veya yeniden derleme yapmak gerekmez.

Trafiğim headscale sunucusundan mı geçer?

Genellikle hayır. Headscale ağı koordine eder, key ve adres dağıtır. Veri yolu ise node'lar arasında doğrudan WireGuard bağlantısı üzerinden çalışır. İki node birbirine doğrudan erişemediğinde ve DERP relay kullanımına geçtiğinde trafik yalnızca bu durumda dolambaçlı bir yol izler. Paketle birlikte gelen yapılandırmada bu relay'ler Tailscale'in genel relay'leridir. Belirli bir peer'in direct durumunda mı olduğunu veya relay üzerinde mi bulunduğunu görmek için bir node üzerinde tailscale status komutunu çalıştırın.

Node'um kayıt olduktan sonra neden offline durumda kalıyor?

headscale nodes list içinde görünen ancak hiçbir zaman online olmayan bir node için reverse proxy dahil olmak üzere control bağlantısı kontrol edilmelidir. Bu bağlantı, Upgrade: tailscale-control-protocol header'ı ile POST olarak gönderilen bir HTTP upgrade isteğidir. nginx, Upgrade ve Connection header'larını proxy_set_header ile açıkça iletmediğiniz sürece bu isteği düşürür. Yukarıdaki yapılandırma bunu map $http_upgrade $connection_upgrade bloğu üzerinden yapar. Bu header'ların düşürülmesi yeni node'ların kayıt olmasını da engeller. Caddy bu isteği ek yapılandırma olmadan iletir. Bu nedenle proxy'nin sorumlu olup olmadığını hızlıca test etmek için kullanılabilir.

headscale için domain name ve TLS gerekiyor mu?

Bu kurulum için evet: domain name ve HTTPS kullanın. Sertifikalar çıplak IP adreslerini de kapsayabilir. Ancak yapılandırma dosyası DERP için TLS gerektiğini belirtir. Domain ve Caddy kullanıldığında yaklaşık beş dakika içinde kendini yenileyen bir HTTPS endpoint elde edilir. Plain HTTP kullanılabilir. Ancak headscale dokümantasyonu production ortamında 443 numaralı port üzerinden HTTPS kullanılmasını güçlü biçimde önerir. Ayrıca bazı durumlarda Tailscale istemcisinin 443 numaralı portta HTTPS kullanılacağını varsaydığını belirtir.