Ana içeriğe geç

Kaynak: docs/TROUBLESHOOTING.md — bu sayfa her build'de otomatik senkronize edilir.

Sorun Giderme

Süreç trafiği / DNS / L7 panelleri boş​

Bu üç panel agent'ın süreç-atıf motorundan gelir. Yöntem collect.method ile seçilir (auto varsayılan) ve /api/v1/agents yanıtındaki attr_method alanında + agent detay sayfasındaki rozet'te görünür.

Platformauto sırasıGereksinim
LinuxeBPF (+ L7 için yardımcı pcap) → pcapeBPF: kernel ≥ 5.8 + /sys/kernel/btf/vmlinux + CAP_BPF/CAP_SYS_ADMIN (veya root). pcap + L7 yardımcı: CAP_NET_RAW + libpcap
Windowspcap (MSI Npcap'i kurar) → ETWNpcap (npcap.com, MSI otomatik kurar). Npcap yoksa ETW: yükseltilmiş süreç — L7 akmaz
macOSpcapsudo (/dev/bpf* root dışında kapalı)

Kontrol listesi:

  1. Derin toplama v1.3.0'dan beri varsayılan açık — collect.pcap / -pcap gerekmez. agent.log'da surec atfi kapali — collect.method=off görüyorsanız agent.yml'de collect.method: off var demektir; kaldırın.
  2. Hub politikası açık mı? -agent-pcap v1.3.0'dan beri varsayılan açık. agent.log: PCAP politikasi hub tarafinda kapali → hub -agent-pcap=false ile başlatılmış (veya hub.yaml'de agent_pcap: false); kaldırın.
  3. agent.log'da hangi yöntem seçildi? surec atfi aktif yontem=ebpf iface=… gibi bir satır olmalı. yontem=pcap ise eBPF/ETW ortamı uygun değildir; surec atfi baslatilamadi satırındaki err= / cozum= nedeni söyler.
  4. Motor çalışıyor (surec atfi aktif) ama paneller yine boş → yanlış arayüz. Yalnızca pcap yönteminde olur: agent, hub'a/internete giden varsayılan-rota arayüzünü seçer ve Tailscale/WireGuard/utun* gibi sanal adaptörleri eler. Yine de yanlış arayüz seçildiyse (örn. tek fiziksel NIC yok, ya da tüm trafik bir VPN'den akıyor) agent.yml'de açıkça verin: 
    collect:
      pcap_interface: "Ethernet"   # Windows: Get-NetAdapter · Linux/macOS: ip -o link / ifconfig
    Agent detay sayfasındaki Atıf rozeti dinlenen arayüzü pcap @ Tailscale biçiminde gösterir; panel boş-durum metni de aynı ipucunu verir.
  5. eBPF yüklenmedi: eBPF nesnesi yüklenemedi → kernel < 5.8 ya da BTF yok (CONFIG_DEBUG_INFO_BTF=y gerekir; RHEL/Debian ≥ 11 var, bazı minimal imajlarda yok). Seçici otomatik pcap'e düşer.
  6. Windows ETW başlamadı: yükseltilmemiş süreç → ETW atlandı: süreç yükseltilmemiş. Servis olarak kurulduysa SYSTEM'dir; elle çalıştırıyorsanız "Yönetici olarak çalıştır".
  7. attr_method=off rozeti üç anlama gelir; hangisi olduğunu rozetin yanındaki not (ve /api/v1/agents → attr_note) söyler: collect.method=off (config), hub PCAP politikasi kapali (-agent-pcap=false) (hub), ya da bir başlatma hatası ipucu (Npcap yok / kernel eski / arayüz yok).

Windows'ta Npcap​

v1.3.0'dan beri MSI kurulumu Npcap'i sessizce indirip kurar (deploy/msi/install-npcap.ps1 — npcap.com'dan, SHA-256 + Authenticode imza doğrulamalı) ve agent collect.method: pcap ile gelir → L7 (SNI/Host) Windows'ta da çalışır.

Npcap kurulamazsa (internet yok, imza/hash uyuşmadı) MSI yine başarıyla biter; agent otomatik ETW'ye düşer → süreç trafiği + DNS akar, L7 akmaz (method: pcap seed'i zorlanmış olsa da yükseltilmiş Windows'ta ETW yedeği devreye girer). agent.log: pcap arka ucu (L7/SNI dahil) icin Npcap gerekir

  • ardından atif arka ucu kurulamadi, siradaki deneniyor yontem=pcap. L7 istiyorsanız Npcap'i elle kurup servisi yeniden başlatın (sc stop bazntms-agent && sc start bazntms-agent). Npcap kurulum günlüğü: C:\ProgramData\bazntms\npcap-install.log.

Hava boşluklu / internet erişimi olmayan Windows makineleri: Npcap'i önceden kurun, MSI kurulumu onu tespit edip atlar.

Derleme için Npcap SDK / mingw-w64 GEREKMEZ (Windows agent CGO_ENABLED=0; wpcap.dll çalışma anında yüklenir, gopacket Npcap dizinini otomatik bulur).

Arayüz listesi boş / seçilen arayüz trafik göstermiyor​

  • Sadece up ve loopback olmayan arayüzler listelenir
  • VPN/filtre sürücüleri trafiği başka sanal arayüze taşıyabilir; doğru arayüzü seçin

"Error opening adapter" / "dosya adı veya birim etiketi söz dizimi hatalı" (Windows)​

-collect-method=pcap seçildi, Npcap kurulu ama başlamıyor:

WARN surec atfi baslatilamadi — telemetri surecek  iface=Ethernet  err="Error opening adapter: ..."

libpcap Windows'ta arayüzü \Device\NPF_{GUID} biçiminde ister; Ethernet / Wi-Fi gibi friendly ad çalışmaz (hata 123, ERROR_INVALID_NAME). Agent v0.2.3+ collect.pcap_interface boş/auto ise friendly adı otomatik NPF adına çevirir. Elle vermek isterseniz:

Get-NetAdapter | Select-Object Name, InterfaceGuid

sonra C:\ProgramData\bazntms\agent.yml (tek tırnak — YAML'da \ literal kalır):

collect:
  pcap: true
  pcap_interface: '\Device\NPF_{BULUNAN-GUID}'

sc stop bazntms-agent && sc start bazntms-agent, ardından agent.log'da surec atfi aktif satırını bekleyin. L7 (SNI/Host) için yakalama başladıktan sonra açılan HTTPS bağlantıları gerekir; mevcut bağlantılar sayılmaz.

Windows MSI / servis kurulumu​

"Service bazNTMS agent failed to start" (hata 1920)​

MSI, servisi kurulum anında başlatmaz — config doldurulmadan başlayan servis hata verip kurulumu düşürürdü. MSI'ı çift tıklarsanız sihirbaz Hub adresi/ enroll token/site alanlarını zaten sorar; komut satırından sessiz kurulumda sıra:

:: 1. Kurulum — sunucu bilgisi opsiyonel property olarak verilebilir (/qn: sihirbazı atla)
msiexec /i bazntms-agent-amd64.msi /qn HUBURL=https://hub.example.com ENROLLTOKEN=xxx SITE=ofis-a

:: 2. Servisi başlat (config'e girmişseniz property vermenize gerek yok)
sc start bazntms-agent
  • Property'ler HKLM\SOFTWARE\bazNTMS\Agent altına yazılır; agent önceliği flag > registry > config.yml şeklindedir. Yönetilen/GPO kurulumlarda property'lerin geçmesi için kurulumu yükseltilmiş (elevated) komut satırından çalıştırın.
  • Config'i elle dolduracaksanız: C:\ProgramData\bazntms\agent.yml içindeki hub.url ve hub.token değerlerini girin, sonra servisi başlatın.
  • Servis başlamıyor ama MSI kurulduysa: servis modunda loglar C:\ProgramData\bazntms\agent.log dosyasına yazılır (v0.2.2+) — en sık neden: hub adresine erişilemiyor (enrollment başarısız) veya token hatalı. Eski sürümde servis logları kaybolur; binary'yi interaktif çalıştırıp hatayı görün: 
    "C:\Program Files\bazNTMS\bazntms-agent.exe" -config "C:\ProgramData\bazntms\agent.yml"
  • Servis kurulumu hata 1053 veriyorsa (zaman aşımı) binary eski bir sürüm olabilir; SCM dispatcher desteği v0.2.1 ile geldi — release'ten güncel MSI'ı alın.

"hata 1603" + logda SECUREREPAIR: SecureRepair Failed / ProcessComponents. Return value 3​

Aynı sürüm zaten kuruluyken msiexec /i bazntms-agent-amd64.msi çalıştırmak kurulum değil, bakım/onarım işlemi başlatır. Windows Installer önbelleğindeki orijinal paketi doğrulamaya çalışır (SECUREREPAIR); indirdiğiniz dosyanın adı önbellektekiyle uyuşmadığı için (bazntms-agent-amd64_3.msi gibi sayı ekli adlar bunun işaretidir) doğrulama başarısız olur → ProcessComponents geri döner → rollback → 1603. Dosya bozuk değildir, kurulum eksik değildir.

Doğrulama:

Get-Package '*bazNTMS*'                                  # zaten kurulu mu?
Get-Service bazntms-agent                                # servis kayıtlı mı?

Yalnızca yeniden yapılandırmak istiyorsanız — tekrar kurmayın: ürün zaten kuruludur, sadece kayıt defterini düzenleyip servisi başlatın:

$k = 'HKLM:\SOFTWARE\bazNTMS\Agent'
Set-ItemProperty $k hub_url      'https://hub.example.com'
Set-ItemProperty $k enroll_token 'ent_...'
# saha: Set-ItemProperty $k site 'ofis-a'
Restart-Service bazntms-agent
Get-Content C:\ProgramData\bazntms\agent.log -Tail 20

Gerçekten sıfırdan kurmak istiyorsanız — önce kaldırın, sonra kurun (/i üstüne /i değil):

$p = Get-Package '*bazNTMS*'
msiexec /x $p.FastPackageReference /qn /l*v "$env:TEMP\baz-x.log"
msiexec /i "$env:TEMP\bazntms-agent.msi" /qn /l*v "$env:TEMP\baz-i.log" `
  HUBURL=https://hub.example.com ENROLLTOKEN=ent_...

Sihirbazın verdiği güncel kurulum komutu bu kaldır-sonra-kur sırasını zaten uygular (S12.4 sonrası) — eski bir komut kopyaladıysanız panelden yenisini alın.

Agent filosu​

Uzun hub kesintisi sonrası bir agent'ın verisinde boşluk​

Hub'a ulaşamayan agent her telemetri batch'ini diskteki offline kuyruğa (<state-file>.queue.jsonl, 0600) yazar ve hub dönünce hepsini sırayla oynatır. Kuyruk tavanı 100 batch (varsayılan 30 sn aralıkta ~50 dk); daha uzun kesintide en eski batch'ler atılır ve agent logu bunu belirtir:

WARN offline kuyruk dolu — en eski batch'ler atildi (veri kaybi) atilan=N toplam_atilan=M

Bu, o pencerede kalıcı veri kaybıdır (agent tarafında tampon sınırlı). Kesinti sırasında agent gönderim denemelerini üstel olarak geri çeker (aralık ×2, ×4, ×8; en fazla 5 dk) + ±%20 jitter — 5000 agent'ın hub dönünce onu aynı anda dövmemesi için. Kuyruk (dolmadıysa) tam replay eder, boşluk oluşmaz.

Agent logu "hub daha eski protokol konusuyor — agent degrade ediyor"​

Agent, hub'dan yeni bir sürüm (daha yüksek protocol_version). Hub sert reddetmek yerine (eski davranış: 401) agent'ı kabul eder ve HubReply'de kendi sürümünü bildirir; agent o sürüme göre çalışır (telgraf JSON ileri/geri uyumlu). Çözüm: hub'ı da güncelleyin — degrade yalnızca geçiş dönemi içindir.

Agent'lar sayfasında yanlış/beklenmedik IP adresi görünüyor​

Hub, agent'ın IP'sini X-Forwarded-For başlığından (varsa) okur, yoksa doğrudan bağlantının kaynağına düşer. deploy/docker-compose.scale.yml gibi bir nginx LB arkasında (bkz. deploy/nginx/lb.conf) çalışırken LB X-Forwarded-For eklemiyorsa ya da hub LB'nin arkasında değil de doğrudan agent trafiğini alan farklı bir proxy'nin arkasındaysa, gösterilen IP o ara katmanın (proxy/LB container'ı) kendi IP'si olarak görünür — gerçek agent IP'si değil. Bu alan yalnızca gösterim amaçlıdır; erişim kontrolü/rate-limit için kullanılmaz (kimlik doğrulama enroll/agent token'larıyla yapılır).

Agent detayında Süreçler / DNS / L7 panelleri boş​

Ana tanı yukarıdaki Süreç trafiği / DNS / L7 panelleri boş bölümünde. Bu panellere özel iki ek not:

  1. .pkg / MSI / deb / rpm yeniden kurulumu mevcut agent.yml'e dokunmaz; dosya yoksa sihirbaz yeni bir tane üretir (v1.3.0+ → collect.method: auto). Eski bir kurulumda collect.method: off ya da collect.pcap: false kalmışsa: collect.pcap artık yok sayılır, ama method: off hâlâ kapatır — o satırı silin.
  2. Docker/Alpine agent'larında yalnızca kendi çıkış trafiği varsa (örn. yalnız hub'a konuşan sentetik agent) L7 boş kalabilir: sanitizeHost noktasız tek etiketli host adlarını (lb gibi) eler — gerçek FQDN hedeflerine giden trafik gerekir. Konteynerde eBPF/pcap için --network=host + --cap-add=NET_RAW --cap-add=NET_ADMIN (eBPF ayrıca /sys BTF erişimi) gerekir.

Agent'lar otomatik güncellenmiyor​

Otomatik güncelleme varsayılan açık ve genelde hiçbir müdahale gerektirmez (bkz. UPGRADE-RUNBOOK.md §2). Beklemeden önce ilk kontrol edilecek şey sürüm: bazntms-agent -version (veya agent detay sayfası). v1.4.2'den eski bir agent restart edilse bile 30 dk gibi kısa bir sürede güncellenmemiş olabilir, bu normaldir — o sürümler açılışta hiç kontrol etmez, yalnızca update.interval_hours (varsayılan 6 saat) sonraki ilk tik'i bekler. v1.4.2+ agent'lar açılışta hemen bir kez kontrol eder.

Bir agent hiç (6+ saat geçse de) güncellenmiyorsa, aşağıdakini agent logunda arayın:

WARN guncelleme kontrolu basarisiz err="yeni binary yerlestirme: rename ... invalid cross-device link"

Bu, v1.4.1 ve öncesindeki bir bug'dır (yalnızca Linux): indirilen güncelleme OS'un varsayılan geçici dizinine (/tmp) yazılıyordu; hedef binary farklı bir dosya sistemindeyse (/tmp ayrı bir tmpfs mount'uysa — sertleştirilmiş imajlarda yaygın) atomik rename bu hatayla her seferinde başarısız olur. Etkilenen bir agent kendi kendine iyileşemez — çalışan eski binary aynı hatayla kendini değiştirmeye çalışmaya devam eder; otomatik kanal o makinede işe yaramaz. Yalnızca bu durumda, o makineyi bir kez elle güncelleyin (installer'ı tekrar çalıştırın ya da servisi durdurup binary'yi elle değiştirin — bkz. UPGRADE-RUNBOOK.md §3); v1.4.2 sonrası bug'a hiç girmediği için bir daha elle müdahale gerekmez.

Hub tarafını da kontrol edin — GitHub'dan yeni sürümü çekebiliyor mu:

# hub logunda:
# "agent güncelleme kanalı yenilendi" ... version="vX.Y.Z" → beklenen sürüme geçti
# "agent güncelleme senkronu başarısız" err=... → GitHub'a çıkış (egress) engelli olabilir

AI analizi sorunları (Faz 26)​

"AI analiz kapalı" / /ai sekmesi görünmüyor​

  • Hub -ai bayrağıyla başlatılmalı.
  • Sekme yalnız PermAnalyze olan rollere (admin / site-admin / netops / analyst) görünür — viewer göremez.

"etkin AI sağlayıcısı yok"​

Yönetim > AI Sağlayıcı'dan bir model ekleyin (yerel: Ollama/LM Studio; bulut: OpenAI/Anthropic). Ya da -llm-base-url ile bootstrap seed edin.

"ai.allow_cloud kapalı — yalnızca yerel model adresleri kabul edilir"​

Egress kilidi açık (-ai-allow-cloud=false). Bulut sağlayıcı kullanmak için =true yapın; yerel model için Ollama/LM Studio adresini kullanın.

"AI boş yanıt döndü" / "token limitini aştı"​

Reasoning modeller (Qwen3, DeepSeek-R1) cevaptan önce uzun düşünme üretir. Sağlayıcı düzenleme dialog'unda no_think=1 (Qwen3) ya da max_tokens artırın. reasoning_content + <think> blokları otomatik temizlenir.

"AI servisine ulaşılamadı" / "Test Et" başarısız​

  • Yerel sunucu çalışıyor mu? (curl localhost:11434/v1/models)
  • Ollama'da model çekilmiş mi? (ollama pull gemma3)
  • Docker'da hub → host Ollama: -llm-base-url http://host.docker.internal:11434/v1

Sohbet akışı "donuyor" (nginx LB arkasında)​

deploy/nginx/lb.conf'ta /api/v1/ai/ konumunda proxy_buffering off var mı? Hub X-Accel-Buffering: no gönderir ama LB tamponu bunu ezebilir.

Gecelik analiz / triyaj notu üretilmiyor​

  • ai.nightly.enabled / ai.triage.enabled YAML'de açık mı?
  • Çoklu controller: yalnız lider replika çalıştırır (scheduler C1).
  • Triyaj yalnız min_severity ve üstü yeni incident'lara; saatlik max_per_hour sınırı var (aşımda log satırı).

GeoIP​

  • Bayraklar görünmüyorsa: geoip/ altında GeoLite2-Country.mmdb + GeoLite2-ASN.mmdb var mı? Yoksa ip-api modu çalışır (internet ister, -ip-api-lookup=false ile kapanır)
  • ip-api.com ücretsiz kotası dakikada 45 istektir; kota dolunca 1 dk bekler
  • Özel ağ IP'leri (192.168.x.x) bilinçli olarak çözümlenmez

Bildirimler​

  • macOS masaüstü bildirimi çıkmıyor: Sistem Ayarları → Bildirimler → (osascript'i kullanan terminal uygulaması) izinlerini kontrol edin
  • Windows: BurntToast PowerShell modülü kurulu olmalı: Install-Module BurntToast
  • Linux: notify-send paketi kurulu olmalı
  • Webhook hataları sunucu log'una düşer; bildirim hatası izlemeyi durdurmaz

Performans / veri​

  • Veri tabanı çok büyüdü: -retention-hours değerini düşürün (ör. 72). Temizlik 10 dakikada bir çalışır.
  • Paket düşüşü (dropped): UI'daki "Paket Hızı" kartında görürsünüz; ağır trafikte snaplen zaten 65535'tir, düşüş genelde disk/CPU tıkanıklığındandır
  • PCAP dosyaları: -record-max-mb ile dosya boyutunu sınırlayın; kayıt yalnızca yakalama açıkken yazılır

Kimlik doğrulama​

  • Şifrenizi unuttursanız: sunucuyu şifresiz başlatın (auth kapanır) ve yeni şifreyle yeniden başlatın. Şifre hiçbir yere yazılmaz.
  • Oturumlar bellekte tutulur: her yeniden başlatmada yeniden giriş gerekir.
  • 429 Too Many Requests: IP başına 5 hatalı deneme sonrası 1 dk bekleme.

Derleme​

  • go build cgo hatası (macOS): Xcode CLT kurulu mu? xcode-select --install
  • frontend/dist embed hatası: önce cd frontend && npm install && npm run build çalıştırın; make iki adımı sırayla yapar
  • Cross-compile: hedef platformun (cgo kullanan) libpcap'i gerekir — Makefile'daki cross-mac / cross-linux hedefleri yalnızca darwin/linux içindir, Windows hedefi yok (CI'da doğrudan windows-latest runner'ında derlenir, cgo gerekmediği için ek SDK istemez)

Log örnekleri​

level=INFO msg="AI analiz aktif" bulut_izni=false            # -ai açık
level=INFO msg="AI bootstrap sağlayıcı eklendi" kind=ollama  # -llm-* seed etti
level=WARN msg="kimlik dogrulama kapali — ..."               # -auth-password verin
UYARI [port] Şüpheli porta bağlantı: ...                     # uyarı tetiklendi