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

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; bu sınama 443 numaralı port üzerinden yanıtlanır ve internetten sunucunuza erişilebilen bir alan adı gerektirir. Sadece IP adresi kullanmak bu akışta çalışmaz.

VPS'in genel IPv4 adresini işaret eden bir A kaydı (netbird.example.com) oluşturun ve herhangi bir işlem yapmadan önce kaydın yayılmasını bekleyin.

dig +short netbird.example.com

Bu komut, sunucunuzun adresini döndürmelidir. DNS yayılmadan kurulum betiğini ç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 denemeden önce sınırın yenilenmesini beklemeniz gerekir.

İnternetten üç portun erişilebilir olması gerekir: HTTPS yönlendirmesi için TCP 80, dashboard, API, sinyal, relay trafiği ve sertifika sınaması için TCP 443 ve STUN için UDP 3478.

sudo ufw allow 80/tcp
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 panelindedir ve sunucunun kendi ufw status ayarı 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 portunu engellerseniz eşler yine de TCP 443 üzerinden relay aracılığıyla bağlanır, bu yüzden hiçbir şey bozuk görünmez. Ancak her eşte Connection type: Relayed uyarısı alırsınız ve tüm trafik eşler arası yerine VPS'iniz üzerinden geçer.

Yazılım tarafında, Compose v2 eklentisiyle birlikte Docker'a, ayrıca jq ve curl paketlerine ihtiyacınız vardır. Betik; Docker, Compose ve jq varlığını kontrol eder ve eksiklik durumunda durur. Betik, curl paketini kontrol etmeden kullandığı için bunu önceden yükleyin. Eğer sunucuda Docker yeniyse, önce VPS üzerinde Docker Compose kurulumunu tamamlayın.

NetBird sunucusunu hızlı başlangıç betiği ile kurun

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

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 hiçbir kayıt kalmaz. Etiketli bir sürümü indirin, okuyun 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 önce 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şini size bırakır; 5. seçenek ise yalnızca Compose dosyasını yazar ve kurulum belgelerini terminale yazdırır. Bu, halihazırda bir proxy çalıştıran sunucularda doğrudur ancak temiz bir sunucuda yanlıştır. 0 seçeneği daha sonra bir e-posta adresi ister; Traefik bunu Let's Encrypt hesabınızla kaydeder. İstem hala bunu sertifika bildirimleri için bir adres olarak adlandırsa da, Let's Encrypt 4 Haziran 2025 itibarıyla süre sonu e-postaları göndermeyi durdurmuştur; bu nedenle yenileme sorunları gelen kutunuz yerine Traefik günlüklerinde 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 hiçbir işe yaramaz. 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 yazar: docker-compose.yml, 600 modunda 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 kabul edin, çünkü config.yaml deposundaki verileri şifreleyen anahtarı tutar. Bunu kaybetmek, yeniden kurulumla düzeltilebilecek bir durum değildir.

docker compose ps
docker compose logs -f netbird-server

Her servis running dosyasını okumalıdır 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 setup key 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. Setup key, etkileşimli adım gerektirmeden bir makineyi kaydeden bir ön kimlik doğrulama belirtecidir. Dashboard üzerinde Setup Keys bölümünden bir tane oluşturun.

İki tür anahtar mevcuttur. Tek kullanımlık (one-off) anahtar tam olarak bir makinenin kimliğini doğrular ve sonrasında geçersiz hale gelir. Yeniden kullanılabilir (reusable) anahtar ise isteğe bağlı bir sınır ile birçok makineyi kaydeder. Her iki türün de bir son kullanma tarihi vardır ve her ikisi de yeni eşi (peer) otomatik olarak bir gruba atayabilir; böylece makine ağa katıldığı anda o gruba tanımlı erişim kuralları geçerli olur.

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

--hostname, dashboard üzerinde görünen ismi belirler. Bu parametre kullanılmadığında eş, makinenin kendi kendine verdiği ismi alır ve hepsi ubuntu olarak adlandırılmış bir cihaz listesi yönetimi zorlaştırır.

Konteynerler ve kısa ömürlü build agent'ları için anahtarı oluştururken ephemeral (geçici) olarak işaretleyin. Ephemeral anahtar ile kaydedilen eşler, 10 dakikadan uzun süre çevrimdışı kaldıklarında otomatik olarak kaldırılır; bu durum ölü kayıtların eş listesinde birikmesini engeller.

Setup key kullanımını planlamadan ö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ı listesiyle uğraşmak 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 NetBird panelinde dört değer girerek ekleyin: ad, client ID, client secret ve issuer. NetBird size, sağlayıcınıza geri yapıştırmanız gereken bir yönlendirme URL'si verir. 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 genel OIDC olarak eklenebilir. Eğer halihazırda kendi sunucunuzda barındırdığınız bir tek oturum açma (SSO) çözümü olarak Authentik kullanıyorsanız, iki ayrı hesap listesi yerine tek bir liste tutmanızı sağlayacak yöntem budur.

Bir sağlayıcı ekledikten sonra yerel giriş seçeneği kullanılabilir kalmaya devam eder ve yapılandırılan tüm sağlayıcılar giriş sayfasında görünür. Güçlü bir parolaya sahip bir yerel yönetici hesabı tutmaya devam edin. Böylece, hatalı bir OIDC yapılandırması durumunda sisteme erişim yolunuz açık kalır.

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 ise ürünün tamamını sunar: kendi istemcisi, kendi paneli, gömülü bir kimlik sağlayıcısı ve tarayıcı üzerinden düzenlenen erişim politikaları. Bu, VPS üzerinde daha fazla hareketli parça anlamına gelir ancak terminal açmayacak bir iş arkadaşına devretmek için çok daha az iş yükü gerektirir.

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 kurulumu çalıştırmak için ne kadar küçük bir VPS yeterlidir?

Belgelenen minimum gereksinim 1 CPU ve 2 GB bellektir. NetBird'ün kendi notları, kullanıcı yönetimi yerel hale geldiği için mevcut alt sınırı 1 GB RAM civarına çekmiştir; eski yapıda tam bir Zitadel dağıtımı yığının bir parçası olduğunda 2 GB ile 4 GB arası gerekiyordu. 2 GB satın alın. Ekstra boş alan, eski imajlar hala diskteyken yükseltme sırasında yeni imajların çekilmesine olanak tanır.

Küçük bir sunucuda üç şeyi dışarıda bırakmak güvenlidir. Dahili servisleri genel ana bilgisayar adlarında yayınlamak için var olan ve eşlerin (peer) bağlanmasıyla ilgisi olmayan NetBird Proxy servisini reddedin. Komut dosyasının yalnızca proxy ile birlikte sunduğu ve açık bir sunucuya ilk gün yerine daha sonra eklenmeye değer olan CrowdSec'i atlayın. netbird_data birimindeki varsayılan SQLite deposunu koruyun ve yalnızca dağıtımı makineler arasında böldüğünüzde veya gerçek bir eşzamanlılık yüküne ulaştığınızda PostgreSQL'e geçin; bu, daha sonra yapabileceğiniz bir geçiş işlemi olarak belgelenmiştir.

Relay, vazgeçemeyeceğiniz tek bileşendir. NAT'ı her hedef için farklı bir port atayan iki eş, asla doğrudan bir tünel kuramaz; bu nedenle relay, çalışmalarını sağlayan tek yoldur. Devre dışı bırakmak çok az bellek tasarrufu sağlar ve bağlantıları izlenmesi zor bir şekilde keser.

Tek bir sunucu yeterli olmadığında, taşınacak ilk şey relay bileşenidir. 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 bir sertifika alamadı. docker compose logs traefik | grep -i acme komutunu çalıştırın. Bunun iki nedeni olabilir. 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 üzerinde değil, sağlayıcının ağ güvenlik duvarında gerçekleşir. Challenge 443 portu üzerinden yanıtlandığı için 80 numaralı portun açık olması burada bir işe yaramaz. Sorunu gidermeden önce döngü içinde tekrar denemeyin; çünkü Let's Encrypt, ana bilgisayar adı başına saatte yalnızca beş başarısız doğrulamaya izin verir ve bir döngü, limit dolana kadar tekrar deneme yapmanızı engeller.

İstemci bağlandığını söylüyor ancak dashboard boş. İstemci, --management-url eksik olduğu için 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 sudo netbird up --management-url https://netbird.example.com komutunu tekrar uygulayın.

Her eş Connection type: Relayed durumunu gösteriyor. Doğrudan tüneller kurulmuyor, bu nedenle tüm trafik VPS'iniz üzerinden geçiyor ve bir gecikme sıçraması ekliyor. VPS güvenlik duvarında ve sağlayıcı güvenlik duvarında UDP 3478 portunu kontrol edin; çünkü STUN, bir eşin kendi genel adresini ve portunu öğrenmesini sağlayan protokoldür. netbird status --detail ayrıca Direct: false ifadesini ve her eş için ICE (interactive connectivity establishment) aday türlerini yazdırır; bu da bağlantı girişiminin ne kadar ilerlediğini gösterir. Bazı ağlarda yalnızca relay (aktarılan) sonucu alınabilir ve bu durum bir sorun teşkil etmez.

Bir eş katılıyor ancak hiçbir şeye 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 yolundadır. Yerini tespit edemediğ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.

Yedekleme ve yükseltmeler

Tüm kurulumu iki unsur ayakta tutar: docker-compose.yml ve config.yaml dosyalarını barındıran dizin ile veritabanı ve şifreleme anahtarlarını tutan Docker volume. Bunları birlikte yedekleyin. config.yaml, depodaki verileri şifreleyen anahtarı tutar; dolayısıyla bu anahtar olmadan alınan bir veritabanı kopyası, okunabilir hiçbir veriye dönüştürülemez.

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önetebilir.

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 içeren tüm etiketler belirli bir sürüme sabitlenmelidir; kurulum betiğini sabitlemenizle aynı nedenden ötürü: 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 kuran 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. Güncel sürümler yerleşik bir kullanıcı deposu içerir; bu sayede ilk yönetici hesabını https://netbird.example.com adresindeki tarayıcı üzerinden oluşturabilir ve sonrasında panelden kullanıcı ekleyebilirsiniz. Harici bir OIDC sağlayıcısı isteğe bağlıdır ve daha sonra dört değer (ad, client ID, client secret ve issuer) ile eklenebilir. NetBird'den önce Zitadel veya Keycloak kurmanızı öneren kılavuzlar, artık gerekli olmayan bir kurulumu tarif eder; 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 servis 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. NAT'ın her hedef için farklı bir port atadığı bir ağda, tek olası sonuç aktarılan (relayed) bağlantıdır 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ırılan servisine 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, sunucunun yanlış olduğunu doğrular. sudo netbird down komutunu, ardından sudo netbird up --management-url https://netbird.example.com komutunu çalıştırın; eş panelinizde 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çinde 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 kolaydır.

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. Kimlik sağlayıcı artık ayrı bir kurulum yerine gömülü olarak geldiği için, güncel sürümlerde pratik alt sınır yaklaşık 1 GB'a düşmüş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.