SSD Nodes Learn Hosting plans →
Rehberler Matt ConnorYazan Matt Connor

NetBird VPN Sunucusu Kendi VPS Üzerinde Nasıl Kurulur?

NetBird mesh VPN altyapısını kendi VPS sunucunuzda barındırın. DNS, TLS yapılandırması, kurulum anahtarları ve Headscale ile karşılaştırmalı kurulum rehberine göz atın.

NetBird VPN sunucusunu kendi sunucunuzda barındırmanın sağladıkları

NetBird VPN sunucusunu kendi altyapınızda barındırmak, kontrol düzlemini (control plane) sahip olduğunuz bir VPS üzerine taşır: Bu katman, eş (peer) listesini tutar, hangi makinenin hangisine erişebileceğine karar verir ve iki eşin NAT (ağ adresi çevirisi) arkasında birbirini bulmasına yardımcı olur. Tünellerin kendisi yine WireGuard tabanlıdır ve doğrudan makineleriniz arasında şifrelenir. Değişen şey, cihaz envanterinizi veya giriş akışınızı hiçbir dış şirketin tutmuyor olmasıdır. Bunun size ne kazandırdığını net bir şekilde anlamalısınız; çünkü barındırılan bir kontrol düzlemi de trafiğinizi şifreleyen anahtarları asla tutmaz ve bir koordinasyon sunucusunun ele geçirilmesi durumunda aslında neler yapabileceği, çoğu insanın okumadan önce varsaydığından çok daha sınırlı bir listedir.

NetBird, halihazırda bildiğiniz iki şeyin arasında yer alır. Bir mesh overlay yapısıdır; yani eşler, her şeyi tek bir ağ geçidi üzerinden göndermek yerine birbirlerine doğrudan bağlanırlar. Aynı zamanda uçtan uca kendi sunucunuzda barındırılabilir; bu da onu Headscale, kendi sunucunuzda barındırılan Tailscale kontrol sunucusu ile karşı karşıya getirir. Eğer şimdiye kadar yalnızca tek bir ağ geçidi olan bir tünel çalıştırdıysanız, önce standart WireGuard ile mesh overlay arasındaki fark konusunu okuyun; çünkü bu sayfanın geri kalanını anlamlı kılan zihinsel model budur.

Eğer aslında istediğiniz, tüm trafiğinizin çıkış yaptığı tek bir sunucu ise, bir mesh yapısı bu iş için gerekenden daha fazla karmaşıklık içerir. Tek bir VPS üzerinde standart bir WireGuard VPN veya bir Tailscale çıkış düğümü (exit node), bu işi çok daha az operasyonel yükle yapar. Eğer hedefiniz makineleri birbirine bağlamak yerine tek bir özel ağa erişmekse, bir VPS üzerindeki Tailscale alt ağ yönlendiricisi (subnet router), aşağıdaki yığının hiçbirine ihtiyaç duymadan bu IP aralığını mevcut tailnet ağınıza duyurur.

Yığının gerçekte ne çalıştırdığı

Düzen yakın zamanda değişti ve eski dokümanların çoğu eski yapıyı anlatmaktadır. Ekim 2026 itibarıyla v0.80.0 ve bu kılavuzun temel aldığı v0.76.2 sürümleri üzerinde yapılan kontrollerde, hızlı başlangıç betiğinin varsayılan olarak üç servisli bir Compose dosyası oluşturduğu görülmüştür.

  • netbird-server yönetim API'sini, sinyal servisini, gömülü STUN dinleyicisine sahip röleyi ve gömülü kimlik sağlayıcısını barındırır. Eski sürümlerde bunlar ayrı container'lardı ve kimlik sağlayıcısı, önceden ayrıca kurmanız gereken bağımsız bir Zitadel kurulumuydu.
  • dashboard yönetici web konsoludur.
  • traefik TLS (transport layer security) sonlandırmasını yapar ve ilk başlatmada Let's Encrypt üzerinden sertifika talep eder.

İki servis daha mevcuttur ancak siz bir istemde onay vermediğiniz sürece kapalı kalırlar. NetBird Proxy servisi, iç servisleri genel ana bilgisayar adları üzerinden yayınlar. CrowdSec ise kötü niyetli trafiği filtreler. Çalışan bir mesh yapısı kurmak için ikisine de gerek yoktur ve her ikisi de küçük bir sunucuda bellek tüketir.

Eğer tek bir Docker container içinde wg-easy yapısından geliyorsanız, bu bileşen sayısında bir artış anlamına gelir. Bunun size sağladığı avantajlar; erişim politikaları, kullanıcı bazlı hesaplar ve eşlerin (peer) bir ağ geçidi üzerinden değil, doğrudan birbirlerine bağlanabilmesidir.

Başlamadan önce gereksinimler

Halka açık bir alan adı zorunludur. Dashboard, API ve relay servislerinin tamamı 443 numaralı port üzerinden HTTPS kullanır. Traefik, sertifikasını Let's Encrypt üzerinden TLS-ALPN-01 sınaması ile alır ve bu sınama 443 numaralı port üzerinden yanıtlanır; bu işlem için internet üzerinden VPS adresinize çözümleme yapan bir alan adı gerekir. Salt IP adresi bu akışta çalışmaz.

VPS'in genel IPv4 adresine işaret eden bir adet A kaydı oluşturun, netbird.example.com ve herhangi bir işlem başlatmadan önce kaydın yayılmasını bekleyin.

dig +short netbird.example.com

Bu komut, sunucunuzun adresini döndürmelidir. DNS yayılımı tamamlanmadan yükleyiciyi çalıştırmak, sertifika isteğinin ilk başlatmada başarısız olmasına neden olur. Tekrarlanan başarısız doğrulamalar Let's Encrypt hız sınırlarına (rate limits) takılır; bu durumda tekrar deneme yapabilmek için sınırın sıfırlanmasını beklemeniz gerekir.

Varsayılan kurulumda internete yalnızca iki port açık olmalıdır: Dashboard, API, sinyal ve relay trafiği ile sertifika sınaması için TCP 443 ve STUN için UDP 3478. Traefik tarafından dinlendiği için TCP 80 yerel olarak boş olmalıdır, ancak bu portun dış dünyaya açık olması gerekmez. 80 numaralı porta dış erişimi engellemek, yalnızca HTTP'den HTTPS'e yönlendirmeyi devre dışı bırakır.

sudo ufw allow 443/tcp
sudo ufw allow 3478/udp
sudo ufw reload
sudo ufw status

Bu portları servis sağlayıcınızın ağ güvenlik duvarında da açın. Bu ayar çoğu VPS panelinde ayrı bir kontrol mekanizmasıdır ve ufw status çıktısı doğru görünmesine rağmen bağlantıların reddedilmesinin temel sebebidir.

STUN (session traversal utilities for NAT), bir eşin (peer) kendi NAT'ı tarafından atanan genel adres ve portu öğrenmesini sağlar; böylece iki eş doğrudan tünel kurmayı deneyebilir. UDP 3478 engellenirse eşler yine de TCP 443 üzerinden relay aracılığıyla bağlanır, dolayısıyla hiçbir şey bozuk görünmez. Doğrudan yol bulamayan eşler Connection type: Relayed durumunu gösterir ve trafikleri eşler arası (peer to peer) yerine VPS'iniz üzerinden geçer. Aynı yerel ağdaki (LAN) eşler, yerel adreslerini kullanarak doğrudan bağlanmaya devam edebilir.

Yazılım tarafında, Compose v2 eklentisi ile birlikte Docker ve ayrıca jq ile curl gereklidir. Betik; Docker, Compose ve jq varlığını kontrol eder ve eksiklik durumunda durur. curl aracını kontrol etmeden kullandığı için bunu önceden yükleyin. Eğer Docker bu sunucuda yeniyse, önce VPS üzerinde Docker Compose kurulumunu tamamlayın.

Dahili reverse proxy kullanılmadığında gereken portlar

Traefik olmadan, birleşik sunucu yönetim, sinyal ve relay servislerini tek bir HTTP arka ucunda taşımaya devam eder, bu nedenle port listesi neredeyse hiç değişmez. Oluşturulan Compose dosyası şunları yayınlar:

  • TCP 8080, dashboard, varsayılan olarak 127.0.0.1 adresine bağlı
  • TCP 8081, netbird-server, varsayılan olarak 127.0.0.1 adresine bağlı
  • UDP 3478, STUN, doğrudan yayınlanır

Kendi proxy'niz TLS termination işlemini TCP 443 üzerinde yapar ve bu iki yerel porta yönlendirir. STUN hiçbir zaman proxy üzerinden geçmez, bu nedenle UDP 3478 her iki durumda da güvenlik duvarında açık kalmalıdır. Yönetim gRPC, sinyal gRPC ve relay için ayrı portlar listeleyen kılavuzlar, eski çoklu container yapısını tarif etmektedir.

Bu yöntemi yalnızca sunucunuzda başka bir servis için halihazırda TLS termination yapılıyorsa seçin. Aksi takdirde, dahili Traefik kullanımı daha az kural ve daha az hata payı anlamına gelir.

NetBird sunucusunun hızlı kurulum betiği ile yüklenmesi

Belgelenen tek satırlık komut, en güncel sürümü doğrudan bir kabuğa aktarır:

curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh | bash

Bunun yerine sürümü sabitleyin. latest değiştiği için, iki hafta arayla çalıştırılan aynı komut iki farklı kurulum üretir ve disk üzerinde hangisinin yapılandırmanızı oluşturduğuna dair bir kayıt tutulmaz. Etiketli bir sürümü indirin, içeriğini inceleyin ve ardından çalıştırın.

mkdir -p ~/netbird
cd ~/netbird
curl -fsSL -o getting-started.sh \
  https://github.com/netbirdio/netbird/releases/download/v0.76.2/getting-started.sh
less getting-started.sh
bash getting-started.sh

Betik ilk olarak alan adını sorar:

Enter the domain you want to use for NetBird (e.g. netbird.my-domain.com):

Ardından TLS'nin nasıl yönetileceğini sorar:

Which reverse proxy will you use?
  [0] Traefik (recommended - automatic TLS, included in Docker Compose)
  [1] Existing Traefik (labels for external Traefik instance)
  [2] Nginx (generates config template)
  [3] Nginx Proxy Manager (generates config + instructions)
  [4] External Caddy (generates Caddyfile snippet)
  [5] Other/Manual (displays setup documentation)
Enter choice [0-5] (default: 0):

[0] seçeneğini tercih edin. 2 ile 4 arasındaki seçenekler bir yapılandırma parçası yazar ve bağlantı işlemlerini size bırakır; 5 numaralı seçenek ise Compose dosyasını, dashboard.env ve config.yaml dosyalarını yazar ve kurulum belgelerini terminale yazdırır. Bu, halihazırda bir proxy çalıştıran sunucularda doğru, temiz bir sunucuda ise yanlıştır. 0 numaralı seçenek, Traefik'in Let's Encrypt hesabınızla kaydettireceği bir e-posta adresi ister. İstemi hala sertifika bildirimleri için bir adres olarak adlandırsa da, Let's Encrypt 4 Haziran 2025 itibarıyla son kullanma e-postaları göndermeyi durdurmuştur; bu nedenle yenileme sorunları gelen kutunuzda değil, Traefik günlüğünde görünür.

İlk kurulumda NetBird Proxy servisine hayır deyin. Bu servis, netbird.example.com adresine yönlendiren bir *.netbird.example.com CNAME kaydı daha ister ve basit bir mesh yapısı için herhangi bir işlev sunmaz. CrowdSec istemi yalnızca proxy etkinleştirildiğinde görünür, bu nedenle proxy'yi reddetmek bunu da atlar. Her ikisi de daha sonra eklenebilir.

Betik, mevcut dizine yazma yapar: docker-compose.yml, 600 izin moduyla config.yaml ve dashboard.env. Dahili Traefik ile birlikte, yalnızca NetBird Proxy'yi etkinleştirdiğinizde traefik-dynamic.yaml ve proxy.env dosyalarını ekler. Bu dizini korumanız gereken durum verisi olarak değerlendirin, çünkü config.yaml depodaki verileri şifreleyen anahtarı tutar. Bu anahtarın kaybedilmesi, yeniden kurulumla düzeltilebilecek bir durum değildir.

docker compose ps
docker compose logs -f netbird-server

Her servis running dosyasını okumalı ve sunucu günlüğü döngüsel olarak yeniden başlamak yerine kararlı hale gelmelidir. Sertifikayı ayrıca izleyin:

docker compose logs traefik | grep -i acme

ACME (otomatik sertifika yönetim ortamı), Traefik'in sertifika almak için kullandığı protokoldür. Buradaki hatalar neredeyse her zaman DNS veya kapalı olan 443 numaralı port kaynaklıdır.

İlk yönetici hesabını oluşturma

https://netbird.example.com adresini açın. Yeni bir kurulumda, giriş formu yerine bir kurulum sayfası görüntülenir. Bir e-posta adresi, isim ve parola girin, ardından Create Account butonuna tıklayın. Bu hesap ilk yönetici hesabı olur ve sayfa giriş formuna yönlendirilir.

Bu hesap, netbird-server container içerisinde yerleşik olarak bulunan bir kimlik sağlayıcısı tarafından desteklenen NetBird'ün kendi kullanıcı deposunda tutulur. Dışarıdan herhangi bir bağımlılık yoktur. Bu durum, bir yıl önceki self-hosted NetBird kurulumuna kıyasla en büyük değişikliktir; o dönemde çalışan bir kurulum için önce Zitadel veya Keycloak'un ayağa kaldırılması ve herhangi bir işlem başlamadan önce dört adet OIDC (OpenID Connect) değerinin setup.env dosyasına kopyalanması gerekiyordu.

Kurulum sayfası yerine bir tarayıcı sertifika uyarısı alırsanız, sertifika düzenlenmemiş demektir. Devam etmeden önce bu sorunu giderin; çünkü dashboard, API ile aynı hostname üzerinden iletişim kurar ve hatalı bir sertifika arkasında kafa karıştırıcı şekillerde başarısız olur.

İlk eşinizi (peer) bağlayın

Mesh ağına dahil etmek isterseniz, VPS'in kendisi de dahil olmak üzere herhangi bir Linux makinesine istemciyi kurun:

curl -fsSL https://pkgs.netbird.io/install.sh | sh

Debian ve Ubuntu üzerinde bu betik, NetBird paket deposunu yapılandırır ve ardından istemciyi apt aracılığıyla kurar; böylece paket yöneticisi her iki durumda da kurulumun yönetimini üstlenir. Bir betiği doğrudan shell'e yönlendirmek (piping) sizi rahatsız ediyorsa, önce curl -fsSL -o install.sh https://pkgs.netbird.io/install.sh ile kaydedin ve sh install.sh ile çalıştırmadan önce içeriğini okuyun. Her iki durumda da neyin kurulduğunu doğrulayın:

apt-cache policy netbird

netbird komut satırı istemcisi ve daemon'dır. netbird-ui masaüstü tepsi uygulamasıdır ve başsız (headless) bir sunucuda buna ihtiyaç duyulmaz.

Şimdi istemciyi sunucunuza yönlendirin:

sudo netbird up --management-url https://netbird.example.com

--management-url parametresini atlarsanız istemci, derleme varsayılanı olduğu için NetBird'ün barındırılan hizmetine kaydolur. Komut yine de başarılı olur, makine bir adres alır ancak kendi barındırdığınız (self-hosted) paneliniz boş kalır. Bu durum neredeyse herkesin bir kez düştüğü bir tuzaktır.

Komut, oturum açma işlemini tamamlamak için tarayıcıda açmanız gereken bir URL yazdırır. Sonrasında:

netbird status
ip addr show wt0

netbird status çıktısından dört satır okuyun: Management: Connected, Signal: Connected, mevcut her relay'i bildiren bir Relays: satırı ve overlay aralığında bir NetBird IP:. wt0, NetBird'ün oluşturduğu WireGuard arayüzüdür ve aynı adresi taşıması gerekir.

İkinci bir makineyi kurulum anahtarı ile katılımsız olarak ekleme

Tarayıcısı olmayan ve başında kimsenin bulunmadığı bir makinede tarayıcı üzerinden giriş yapmak mümkün değildir. Kurulum anahtarı, makineyi etkileşimli adım olmadan kaydeden bir ön kimlik doğrulama belirtecidir. Kontrol panelinde Ayarlar → Kurulum Anahtarları (Settings → Setup Keys) bölümünden bir tane oluşturun.

İki tür anahtar mevcuttur. Tek kullanımlık anahtar tam olarak bir makinenin kimliğini doğrular ve ardından geçerliliğini yitirir. Yeniden kullanılabilir anahtar ise, isteğe bağlı bir sınır ile birçok makineyi kaydeder. Her iki tür de isteğe bağlı bir son kullanma tarihine sahip olabilir ve her ikisi de yeni eşi (peer) otomatik olarak bir gruba atayabilir; böylece makine sisteme dahil olduğu anda o gruba ait erişim kuralları geçerli olur.

sudo netbird up --setup-key <SETUP-KEY> \
  --management-url https://netbird.example.com \
  --hostname build-runner-01

--hostname, kontrol panelinde görünen ismi belirler. Bu parametre kullanılmadığında eş, makinenin kendi kendine verdiği ismi alır; ubuntu ismine sahip çok sayıda girişin bulunduğu bir filo yönetimi kimseye fayda sağlamaz.

Konteynerler ve kısa ömürlü derleme aracıları (build agents) için anahtarı oluştururken geçici (ephemeral) olarak işaretleyin. Geçici bir anahtarla kaydedilen eşler, 10 dakikadan uzun süre çevrimdışı kaldıklarında otomatik olarak kaldırılır; bu durum, eş listesinde ölü girişlerin birikmesini engeller.

Kurulum anahtarlarıyla ilgili planlama yapmadan önce bilinmesi gereken bir sınırlama şudur: Bir anahtarın süresinin dolması veya iptal edilmesi yeni kayıtları durdurur, ancak bu anahtarla daha önce kaydedilmiş makinelerin bağlantısını kesmez. Bir makinenin erişimini kaldırmak, o eşi silmek anlamına gelir.

Hala ayrı bir kimlik sağlayıcısına ihtiyacınız var mı?

Küçük bir kurulum için hayır. Dahili kullanıcı deposu, panel üzerinden oluşturulan hesapları yönetir ve bu, az sayıda kişi için yeterlidir.

Halihazırda bir kimlik sağlayıcınız varsa ve ikinci bir kullanıcı listesi tutmak istemiyorsanız harici bir kimlik sağlayıcısına ihtiyaç duyarsınız. NetBird, OIDC protokolünü destekleyen tüm sağlayıcıları kabul eder. Sağlayıcınızda gizli bir OIDC istemcisi kaydedin, ardından bunu NetBird paneline bir isim, client ID, client secret ve gerektiğinde issuer bilgisiyle ekleyin. NetBird, sağlayıcıya geri yapıştırmanız için bir yönlendirme URL'si (redirect URL) sağlar. Google, Microsoft Entra ID, Okta, Zitadel, Keycloak, Authentik ve Pocket ID için hazır entegrasyonlar mevcuttur; diğer tüm sağlayıcılar ise genel OIDC olarak eklenebilir. Eğer halihazırda kendi sunucunuzda Authentik ile tek oturum açma (SSO) sistemini çalıştırıyorsanız, iki ayrı liste yerine tek bir hesap listesi tutmanızı sağlayacak yöntem budur.

Bir sağlayıcı ekledikten sonra yerel giriş seçeneği kullanılabilir durumda kalır ve yapılandırılan her sağlayıcı giriş sayfasında görünür. Güçlü bir parolaya sahip bir yerel yönetici hesabını mutlaka tutun. Hatalı bir OIDC yapılandırması durumunda sisteme giriş yapabileceğiniz bir yolunuz kalmış olur.

NetBird mü Headscale mi: hangi kontrol düzlemini çalıştırmalısınız?

Her ikisi de istemcilerinizin aksi takdirde bağlanacağı barındırılan kontrol sunucusu bağımlılığını ortadan kaldırır. Ancak bunlar aynı yapıda projeler değildir.

Headscale, Tailscale kontrol sunucusunu yeniden uygular ve siz resmi Tailscale istemcilerini kullanmaya devam edersiniz. Resmi bir web konsolu bulunmaz. Kullanıcıları ve kimlik doğrulama öncesi anahtarları bir yapılandırma dosyası üzerinden headscale komutuyla yönetirsiniz. Topluluk tarafından geliştirilen web arayüzleri mevcuttur ancak bunlar projenin bir parçası değildir. Bu durum, durum bilgisini dosyalarda tutmak ve değişikliklerini sürüm kontrol sisteminde yönetmek isteyenler için uygundur.

NetBird tüm ürünü birlikte sunar: kendi istemcisi, kendi dashboard’u, yerleşik bir identity provider ve tarayıcı üzerinden düzenlenen erişim politikaları vardır. Bu yapı VPS üzerinde daha fazla bileşen çalıştırır ve terminal açmayacak bir ekip arkadaşına devredilmesi çok daha kolaydır. NetBird ile hosted Tailscale arasında, Headscale ile karşılaştırma yapmak yerine gerçekten seçim yapıyorsanız, her ikisi de altyapıda WireGuard kullanır. Bu nedenle NetBird ve Tailscale karşılaştırması, gerçekte hangi noktalarda ayrıştıklarını açıklar: control plane’i kimin işlettiği, erişim kurallarının nasıl yazıldığı ve relay’lerin trafiği nasıl taşıdığı.

Halihazırda Tailscale istemcilerine yatırım yaptıysanız veya mümkün olan en küçük kontrol düzlemini istiyorsanız Headscale kullanın. Eğer birden fazla kişinin eşleri (peers) yönetmesi gerekiyorsa ve bir konsol ile SSO'yu dışarıdan birleştirme zahmetine girmeden kullanmak istiyorsanız NetBird tercih edin. Herhangi birine karar vermeden önce Tailscale ücretsiz planının neleri kapsadığını kontrol edin; çünkü altı kullanıcı sınırına uyan ticari olmayan bir grup, barındırılan bir kontrol düzlemi için hiçbir ücret ödemez, sınırsız kullanıcı cihazına ve başlangıç için 50 etiketli kaynağa sahip olur; bu durumda kendi kontrol düzleminizi çalıştırmak için hiçbir nedeniniz olmayabilir. Bu sınır aşıldığında fatura makine sayısına göre değil kişi sayısına göre artar, bu nedenle Tailscale'in grubunuza ne kadar ücret yansıtacağını hesaplamak, bu yığının size maliyeti olan VPS ve harcanan saatlerle kıyaslayabileceğiniz bir rakam sunar.

Bu kurulum için ne kadar küçük bir VPS yeterlidir?

Belgelenen minimum gereksinim 1 CPU ve 2 GB bellektir. 2 GB RAM kapasiteli bir sunucu satın alın.

Küçük bir sunucuda üç bileşeni kurmamak güvenlidir. Dahili servisleri genel ana bilgisayar adları üzerinden yayınlamak için kullanılan ve eşler arası bağlantıyla ilgisi olmayan NetBird Proxy servisini devre dışı bırakın. Komut dosyasının yalnızca proxy ile birlikte sunduğu ve dış dünyaya açık bir sunucuya ilk gün yerine daha sonra eklenmesi daha mantıklı olan CrowdSec'i atlayın. Varsayılan SQLite deposunu netbird_data biriminde tutun; PostgreSQL'e yalnızca dağıtımı farklı makinelere böldüğünüzde veya gerçek bir eşzamanlılık yüküne ulaştığınızda geçin; bu, daha sonra yapabileceğiniz bir geçiş işlemi olarak belgelenmiştir.

Relay, vazgeçemeyeceğiniz tek bileşendir. NAT yapılandırması her hedef için farklı bir port atayan iki eş, doğrudan bir tünel kuramaz; bu nedenle relay, bağlantının kurulmasını sağlayan tek yoldur. Relay'i devre dışı bırakmak çok az bellek tasarrufu sağlar ancak bağlantıların izlenmesi zor bir şekilde kesilmesine neden olur.

Tek bir sunucu yeterli gelmediğinde, ilk olarak relay bileşenini başka bir yere taşıyın. Bağımsız bir relay, NB_LISTEN_ADDRESS, NB_EXPOSED_ADDRESS, NB_AUTH_SECRET ve NB_ENABLE_STUN ile çalışır. Paylaşılan gizli anahtar (shared secret), relay ve ana sunucuda aynı olmalıdır; aksi takdirde istemciler kimlik doğrulaması yapamaz.

Hata modları ve karşılaşacağınız durumlar

Dashboard bir sertifika uyarısı gösteriyor. Traefik sertifika alamadı. docker compose logs traefik | grep -i acme komutunu çalıştırın. Bunun iki nedeni vardır. Ya dig +short netbird.example.com henüz bu VPS'i döndürmüyordur ya da TCP 443 portu Let's Encrypt ile container arasında bir yerde kapalıdır; bu durum genellikle ufw üzerindeki güvenlik duvarından ziyade sağlayıcının ağ güvenlik duvarında yaşanır. Doğrulama işlemi 443 portu üzerinden yanıtlandığı için 80 portunun açık olması burada bir işe yaramaz. Döngü içinde tekrar denemeden önce sorunu giderin; çünkü Let's Encrypt, ana makine adı başına saatte yalnızca beş başarısız yetkilendirmeye izin verir ve bir döngü, limit dolana kadar tekrar deneme yapmanızı engeller.

İstemci bağlandığını söylüyor ancak dashboard boş. --management-url eksik olduğu için istemci, NetBird'ün barındırılan servisine kayıt oldu. netbird status --detail komutunu çalıştırın ve aslında hangi sunucuyla konuştuğunu belirten Management: satırını okuyun. Management: Connected to https://api.netbird.io:443 ifadesini görmek, istemcinin buluta gittiği anlamına gelir. sudo netbird down komutunu çalıştırın, ardından tekrar sudo netbird up --management-url https://netbird.example.com komutunu uygulayın.

Her eş (peer) Connection type: Relayed durumunu gösteriyor. Doğrudan tüneller kurulmuyor, bu nedenle tüm trafik VPS'iniz üzerinden geçiyor ve gecikmeye neden olan bir sekme ekliyor. VPS güvenlik duvarında ve sağlayıcı güvenlik duvarında UDP 3478 portunu kontrol edin; çünkü bir eşin kendi genel adresini ve portunu öğrenmesini sağlayan şey STUN protokolüdür. netbird status --detail komutu ayrıca Direct: false ifadesini ve her eş için ICE (interactive connectivity establishment) aday türlerini yazdırır; bu da girişimin ne kadar ilerlediğini gösterir. Bazı ağlarda yalnızca "relayed" sonucu alınabilir ve bu durum bir sorun olduğu anlamına gelmez.

Bir eş ağa katılıyor ancak hiçbir yere ulaşamıyor. Mesh yapısında olmak, iki eşin birbiriyle konuşabileceği anlamına gelmez. Buna erişim politikaları karar verir ve hiçbir politika atanmamış bir grup hiçbir yere ulaşamaz. Rotaları ve güvenlik duvarlarını hata ayıklamaya başlamadan önce dashboard üzerindeki politikayı kontrol edin.

netbird status bir daemon sorunu bildiriyor. Servis çalışmıyor. sudo netbird service status ve sudo netbird service start komutlarını kullanın. İstemci günlükleri /var/log/netbird/client.log konumundadır. Çözemediğiniz herhangi bir durum için netbird debug bundle --anonymize --system-info komutu; günlükleri, durumu, rotaları, DNS ayarlarını ve güvenlik duvarı durumunu tek bir arşivde toplar.

Yedeklemeler ve yükseltmeler

Kurulumun tamamını iki unsur taşır: docker-compose.yml ve config.yaml dosyalarını barındıran dizin ile veritabanını ve şifreleme anahtarlarını tutan Docker volume. Bunları birlikte yedekleyin. config.yaml, depodaki hassas verileri şifreleyen anahtarı tutar; dolayısıyla bu anahtar olmadan alınan bir veritabanı kopyası, şifrelenmiş kurulum anahtarlarını ve API token bilgilerini kurtaramaz.

docker volume ls
docker compose down
sudo tar czf netbird-config.tgz -C ~ netbird
docker run --rm -v netbird_netbird_data:/data -v "$PWD":/backup \
  alpine tar czf /backup/netbird-data.tgz -C /data .
docker compose up -d

Compose, volume isimlerinin başına proje dizinini ekler; bu nedenle netbird_data olarak belgelenen volume genellikle netbird_netbird_data olarak görünür. Önce docker volume ls komutunu çalıştırın ve çıktıda verilen ismi kullanın; aksi takdirde yukarıdaki docker run komutu sessizce boş bir volume oluşturur ve hiçbir şeyi arşivlemeden başarısız olur. Arşivleri VPS üzerinde tutmayın. Halihazırda bir yedekleme aracınız varsa, restic veya BorgBackup uzak sunucuya yedekleme kısmını yönetecektir.

Sunucuyu yükseltmek, imajı çekmek ve yeniden oluşturmaktan ibarettir:

docker compose pull
docker compose up -d
docker compose ps

Buna güvenmeden önce docker compose config | grep image: komutunu çalıştırın. latest ibaresini taşıyan her etiket belirli bir sürüme sabitlenmelidir; kurulum betiğini sabitlemenizle aynı nedenden dolayı: neyin çalıştığını bilmek istersiniz ve bir yükseltme hatalı çalıştığında geri dönebileceğiniz bir sürümünüzün olmasını istersiniz. İstemciler, kendilerini yükleyen paket yöneticisi aracılığıyla yükseltilir.

FAQ

NetBird'i kendi sunucumda barındırmak için kendi kimlik sağlayıcıma ihtiyacım var mı?

Hayır. Mevcut sürümler yerleşik bir kullanıcı deposu içerir; bu sayede ilk yönetici hesabını tarayıcı üzerinden https://netbird.example.com adresinde oluşturabilir ve sonrasında kullanıcıları panelden ekleyebilirsiniz. Harici bir OIDC sağlayıcısı isteğe bağlıdır ve daha sonra bir isim, istemci kimliği (client ID), istemci gizli anahtarı (client secret) ve gerektiğinde sağlayıcı adresi (issuer) ile eklenebilir. NetBird'den önce Zitadel veya Keycloak kurmanızı öneren kılavuzlar artık gerekli olmayan bir kurulumu tarif etmektedir; bu kılavuzları takip etmek, fazladan bir servis çalıştırmanıza neden olur.

Neden tüm eşlerim (peers) Connection type: Relayed durumunda görünüyor?

Doğrudan bağlantılar kurulamadığı için trafik, VPS üzerindeki aktarıcı (relay) üzerinden geçmektedir. Bunun yaygın nedeni, eşlerin kendi genel adreslerini ve portlarını keşfetmek için kullandıkları STUN portu olan UDP 3478'in engellenmiş olmasıdır. Bu portu hem VPS güvenlik duvarında hem de sağlayıcınızın ağ güvenlik duvarında açın, ardından netbird status --detail komutunu tekrar çalıştırın ve Direct: satırını inceleyin. Her iki eş de hedef başına farklı port atayan bir NAT arkasındaysa, bağlantının aktarılması beklenen bir durumdur ve herhangi bir yanlış yapılandırma yoktur.

İstemcim bağlandı ancak panelde hiçbir eş görünmüyor. Ne oldu?

İstemci, --management-url parametresi belirtilmediğinde gerçekleştiği üzere, kendi sunucunuz yerine NetBird'ün barındırdığı servise kayıt oldu. netbird status --detail komutu, bağlantı kurulan sunucuyu Management: satırında gösterir; dolayısıyla https://api.netbird.io:443 gibi bir değer, sunucuya bağlı olduğunuzu doğrular. sudo netbird down komutunu, ardından sudo netbird up --management-url https://netbird.example.com komutunu çalıştırın; eşiniz panelde görünecektir.

Kendi sunucumda barındırdığım NetBird, Headscale'den nasıl farklıdır?

Her ikisi de barındırılan bir kontrol sunucusunun yerini sizin çalıştırdığınız bir sunucuyla değiştirir. Headscale yalnızca bir kontrol düzlemidir: onu headscale komutu ve bir yapılandırma dosyası ile yönetirsiniz, resmi bir web paneli yoktur ve resmi Tailscale istemcilerini kullanır. NetBird ise kendi istemcisini, yönetici panelini ve kimlik sağlayıcı entegrasyonunu aynı yığın içerisinde sunar. Headscale'i çalıştırmak daha az kaynak gerektirir ve durumunu dosyalarda tutar. NetBird ise terminal kullanmayacak kişilere teslim etmek için daha uygundur.

Kendi sunucumda barındırdığım NetBird için ne boyutlu bir VPS gerekir?

Belgelenen minimum gereksinim 1 CPU ve 2 GB bellektir; satın almanız gereken değer 2 GB'tır. Kurulum sırasında isteğe bağlı proxy servisini reddedin (bu işlem CrowdSec istemini de atlar) ve gerçekten PostgreSQL'e ihtiyaç duyana kadar varsayılan SQLite deposunda kalın.

Bu yazı işinize yaradı mı?