Ana içeriğe geç

Bölüm 33: Sorun Giderme

İlk Kurulum Sorunları

Kurulum, ilk başlatma ve altyapı düzeyindeki sorunlar (servisin ayağa kalkmaması, port çakışması, altyapı servisleri, sertifika üretimi) Arceris destek ekibi tarafından çözülür; bu tür sorunlarda destek ekibiyle iletişin (dağıtım planlaması için Bölüm 3). Operatör olarak gözlemleyip bildirebilecekleriniz:

  1. Panel erişilemiyor: https://<ARCERIS_HOST>:8443/login açılmıyor ya da yanıt vermiyor.
  2. Hazır-bulunurluk degraded: /readyz "degraded" dönüyor (aşağıdaki "Hazır-Bulunurluk" bölümüne bakın) ya da System Settings → Uyarılar & Sağlık altındaki denetimlerde arıza görünüyor.

Admin Arayüzüne Giriş Sorunları

Kontrol Detay
URL https://<ARCERIS_HOST>:8443/login olduğundan emin olun. Kullanıcı girişi farklı bir URL'dedir: /user/login.
Sertifika Tarayıcıda sertifika uyarısı varsa, Web TLS sekmesinden sertifika durumunu kontrol edin.
Kimlik doğrulama Yerel admin girişi mi, LDAP mi? LDAP bağlantısını Identity sayfasından test edin.
Rol Kullanıcının admin rolü olduğundan emin olun. User Management üzerinden rol atamasını doğrulayın.

Lisans Kaynaklı Özellik Görünmeme Sorunları

Bir menü öğesinin veya sayfanın eksik olması:

  1. System Settings → Runtime → License kartını açın.
  2. "Plan" satırındaki plan adını kontrol edin.
  3. Bölüm 30'daki feature gate referans tablosunda, istenen özelliğin hangi planlarda aktif olduğunu kontrol edin.
  4. Plan doğru ama özellik hala görünmüyorsa, "Check Now" butonuna tıklayarak lisans durumunu yenileyin.

Hazır-Bulunurluk (/readyz) Yavaş veya Hatalı "degraded"

Belirti: İzleme sistemi veya yük dengeleyici /readyz yanıtını beklerken zaman aşımına düşüyor; ya da hiçbir bağımlılık bozuk değilken Arceris "degraded" raporluyor.

Çözüm:

  1. Derin hazır-bulunurluk kontrolleri tek bir bütçe altında paralel çalışır; DNS'siz bir kurulumda tüm derin kontroller yaklaşık 2 saniyede biter (eskiden 14–24 saniye sürebilirdi). Kalıcı yavaşlık görülüyorsa önce Arceris sürümünü doğrulayın.
  2. İptal edilen bir /readyz isteği artık "degraded" sonucunu önbelleğe yazmaz; tek bir iptal sonraki kontrolleri bozmaz.
  3. provider_dns denetimi varsayılan olarak yalnızca uyarı üretir; denetimin hazır-bulunurluğu düşürüp düşürmediği System Settings → Uyarılar & Sağlık altındaki kademe ayarıyla yönetilir (Bölüm 29).

LDAP Giriş Sorunları

  1. Identity sayfasında LDAP bağlantı parametrelerini doğrulayın: Host, Port, Bind DN, Base DN, Search Filter.
  2. Test Connection butonu ile bağlantıyı test edin.
  3. Servis hesabının (Bind DN) yeterli okuma iznine sahip olduğundan emin olun.
  4. Group filter'ın doğru grupları yakaladığını kontrol edin; yanlış filter, kullanıcının hiçbir gruba dahil olmamasına neden olur.

Transparent Proxy Sertifika Sorunları

  1. İstemci cihazda Arceris CA kök sertifikasının güvenilir kökler arasına eklendiğini doğrulayın (dağıtım adımları Bölüm 22).
  2. Kesilen (intercept) alan adlarının ilgili AI host'larını kapsadığını doğrulayın; intercept listesi dağıtım düzeyinde tanımlanır — değişiklik gerekiyorsa destek ekibiyle iletişin.
  3. Tarayıcı geliştirici araçlarından sertifikayı inceleyin: Arceris CA'sı tarafından imzalanmış olmalıdır. Transparent proxy mimarisi ve intercept yapılandırması Bölüm 22'dedir.

Explicit Proxy Bağlantı Sorunları

  1. Proxy portunun (varsayılan 3128) istemciden erişilebilir olduğundan emin olun.
  2. Proxy token'ın doğru biçimde gönderildiğini kontrol edin: Proxy-Authorization: Bearer <token> veya Basic base64(username:proxy_token).
  3. TLS Bump aktifse, bump uygulanacak host listesinin doğru yapılandırıldığını doğrulayın (Bölüm 23); liste dağıtım düzeyinde tanımlanır.

PII / Prompt Guard Beklenen Şekilde Çalışmıyor

  1. İlgili kuralın durumunun enabled olduğunu kontrol edin.
  2. Access Management üzerinden kuralın doğru hedefe (kullanıcı/grup) atandığını doğrulayın.
  3. User Management → Effective Policy modalında, test kullanıcısı için kuralların gerçekten çözümlendiğini kontrol edin.
  4. Response Scanning ayarının System Settings → Runtime sekmesinde etkin olduğunu doğrulayın.
  5. Test senaryosunun gerçek trafik akışıyla (API vs. Browser Proxy) eşleştiğinden emin olun.

Presidio (NLP) Erişilemez; İsim/Konum Gibi Varlıklar Yakalanmıyor

Belirti: PII taramasında yalnız desen kuralları eşleşiyor; isim, konum gibi yalnız NLP ile bulunan varlıklar hiç tutulmuyor. Denetim kayıtlarında nlp_unavailable outcome'u, gateway günlüğünde (dakikada en fazla bir kez) WARN görünüyor.

Çözüm:

  1. System Settings → Uyarılar & Sağlık sekmesindeki "PII NLP motoru (Presidio)" denetimine bakın; NLP olmadan geçen taramaların sayısını gösterir.
  2. System Settings → PII & NLP sekmesinde Presidio Analiz Motoru URL'sini ve motorun çalıştığını doğrulayın.
  3. Türkçe tarama tuzağına dikkat: hazır Presidio kurulumlarında Türkçe model bulunmayabilir; motorun kendi /health uç noktası "OK" derken her çağrı başarısız olabilir. "Motor ayakta" ile "Türkçe tarama çalışıyor" aynı şey değildir — denetim kaydındaki nlp_error detayı gerçek nedeni adlandırır.
  4. "Presidio erişilemediğinde" ayarı davranışı belirler: İlet (yalnız desen kuralları) (varsayılan) istekleri yalnız desen kurallarıyla geçirir; İsteği engelle Presidio erişilebilir olana kadar bu istekleri reddeder. Ayarın ayrıntıları Bölüm 14'tedir.

SIEM Veri Gitmiyor

  1. System Settings → Syslog sekmesinde endpoint'in doğru yazıldığını kontrol edin.
  2. Transport protokolünü doğrulayın: HTTP webhook için http, syslog için udp veya tcp.
  3. "Min Severity" seviyesinin gönderilmek istenen olayın severity'sinden yüksek olmadığından emin olun.
  4. Bearer token gerektiren HTTP endpoint'lerde token'ın doğru ayarlandığını kontrol edin.
  5. Ağ çıkışı ve hedef sistemin erişilebilirliğini doğrulayın.

DNS / NTP Apply Sorunları

  1. System Settings → Host Network & Time sekmesinde capability badge'lerini kontrol edin: "Writable" olmalıdır.
  2. Hata kutusu varsa mesajı okuyun: "Last host apply error: ".
  3. Badge "Writable" değilse ya da hata sürüyorsa host tarafı değişikliklerini destek ekibi uygular; hata mesajıyla birlikte destek ekibiyle iletişin. Apply semantiği ve desteklenen arka uçlar Bölüm 29'dadır.

Storage ve Veritabanı Sorunları

  1. System Settings → System Info sekmesinde "Storage Backend" değerini kontrol edin.
  2. "memory" depolama kullanılıyorsa veri kalıcılığı olmadığını ve yeniden başlatma sonrası sıfırlanacağını unutmayın.
  3. Depolama kaynaklı belirtilerde (veri yazılamıyor, denetim kayıtları düşmüyor, disk doluluğu) destek ekibiyle iletişin.

Log Seviyesini Geçici Olarak Yükseltme

Derin sorun giderme için runtime log seviyesini geçici olarak debug'a yükseltin:

  1. System Settings → Runtime Log Seviyesi (Bölüm 6) ile seviyeyi değiştirin; değişiklik anında etkili olur ve denetim günlüğüne yazılır.
  2. Sorunu yeniden üretin ve log akışını izleyin (kural eşleşmeleri, session tehdit değerlendirmeleri, sınıflandırıcı kararları dahil tüm operasyonel ayrıntılar görünecektir).
  3. İnceleme tamamlandığında seviyeyi mutlaka info'ya geri çevirin; debug seviyesi üretimde yüksek günlük hacmi üretir.

DLP / ICAP Tarama Çalışmıyor

  1. DLP kuralının Active olduğunu ve Fail Open toggle'ının beklendiği gibi yapılandırıldığını kontrol edin.
  2. Kuralın Access Management üzerinden doğru hedefe atandığını doğrulayın (DLP Rules sayfasında Not assigned uyarısı varsa atama eksiktir).
  3. Test Connection butonu ile ICAP sunucusunun erişilebilir olduğunu doğrulayın.
  4. User Encoding ayarını kontrol edin: Symantec DLP için base64 zorunludur, plain seçilirse kullanıcı bazlı kurallar sessizce atlanır.
  5. Audit günlüğünde Action=dlp_scan olaylarını arayın; Result (allowed/logged/blocked) ve Details içindeki icap_status değerlerini inceleyin.
  6. DLP'nin yalnızca transparent proxy yolunda çalıştığını unutmayın; API/explicit proxy yolları henüz bağlı değildir.

Topic Classifier Beklenen Şekilde Çalışmıyor

  1. Prompt Guard kuralında Classifier Model modunun seçili olduğunu ve bir modelin seçildiğini kontrol edin (Pattern Groups modu ile aynı anda kullanılamaz).
  2. Kuralın Access Management üzerinden hedefe atandığını doğrulayın.
  3. Embedding tabanlı modeller harici bir model hizmeti gerektirir; hizmet erişilemezse sınıflandırma atlanır ve istek iletilir (fail-open). Sınıflandırmanın hiç tetiklenmediğinden şüpheleniliyorsa destek ekibiyle iletişin.

Çok Ekli İstekler Reddediliyor (not_scanned_file_cap)

Belirti: İstek not_scanned_file_cap gerekçesiyle reddedildi; denetim kaydında "istek, denetçinin istek başına aldığından fazla dosya taşıyordu" açıklaması var.

Neden ve çözüm:

  1. Ek denetimi istek başına sınırlıdır: bir iletide 128'den fazla ek varsa, ya da kullanıcıya atanmış bir OCR kuralı nedeniyle sınır 32'ye düşmüşse, istek taranmadan iletilmek yerine reddedilir. Ek sayısını azaltın ya da gönderiyi bölün.
  2. Önceki turlardan yeniden oynatılan ekler bu sınırı aşarsa istek reddedilmez, yalnızca kayda geçirilir; geçerli turun ekleri her zaman önce denetlenir.
  3. Uygulanabilir kural fail-open/izleme modundaysa istek denetlenmeden iletilir ve not_scanned_file_cap outcome'uyla kayda geçer; fail-closed kurallarda istek engellenir. Ek sınırlarının işleyişi Bölüm 18'de anlatılır.

Akış Kesintileri: Yarım Cevaplar ve stream_outcome

Belirti: Birleşik gateway istemcisi beklenmedik EOF ile yarım cevap alıyor; ya da günlüklerde akış hataları birikiyor.

Teşhis:

  1. Denetim kaydındaki stream_outcome alanı kesintinin kaynağını ayırır (Bölüm 25):
  2. upstream_cut — sağlayıcı akışı kesti. Gateway cevabı normal bitirmiş gibi kapatmaz; bitiş işareti olmadan bağlantıyı kapatır (istemci beklenmedik EOF görür), böylece yarım cevap tamamlanmış sayılmaz. Maliyet ve denetim satırı kaydedildikten sonra kapatılır. Tekrarlayan upstream_cut, sağlayıcı veya ağ tarafında bir soruna işaret eder.
  3. client_cancelled — istemci akışı yarıda bıraktı. Eskiden her terk edilmiş akış ERROR yazıyordu; artık tek bir INFO satırıdır ve sağlayıcı sorunu değildir. Gerçek sağlayıcı veya çeviri hataları hâlâ ERROR olarak kaydedilir.
  4. Model cevaplarının süresi gateway tarafında sınırsızdır: uzun bir tur dakikalarca sürebilir (eskiden explicit proxy'de 60 saniyelik kesim, API sunucusunda 10 saniyelik yazma zaman aşımı vardı; ikisi de kaldırıldı). Kesintiler hâlâ görülüyorsa istemci ile Arceris arasındaki ağın boşta kalma (idle) zaman aşımlarını ve güvenlik duvarını inceleyin; sınır, istemcinin bağlantıyı bırakmasıdır.

Makine Kaydolmuyor / Makineler Sayfasında Hata Rozetleri

Belirti: Makine kaydı (enrollment) sessizce başarısız; Makineler sayfasında satırda "N başarısız denemeden sonra düzeldi" rozeti ya da makine detayında "Son hata serisi" görünüyor.

Teşhis ve çözüm:

  1. Makine servisi (arceris-agent) her kurulum token'ı hatasını ve check-in hata sınıfı değişimini agent.log'a WARN olarak yazar (method, error_class ve sınırlı detail ile — asla token'ın kendisini yazmaz). Kayıt sessiz kalmaz; önce bu günlüğe bakın. arceris-agent status son hatanın yöntemini (last_error_method) gösterir.
  2. "N başarısız denemeden sonra düzeldi" rozeti geçmiş bilgisidir: sunucuya ulaşamayan makine hata bildiremez; satır, düzelme sonrası ilk başarılı check-in'de bildirilen son hata serisini (adım, hata sınıfı, deneme sayısı, zaman aralığı) 7 gün boyunca taşır. Anlık durum için "Son check-in" kolonuna bakın (Bölüm 13).
  3. SPKI pin uyuşmazlığı: pin tanımlı makinelerde kurulum tek bir pinli istek yapar ve sonucu yazdırır (eşleşiyor / zincir pin'leri / "şimdi doğrulanamadı") — kurulum hiçbir zaman bu yüzden başarısız olmaz, çevrimdışı kurulumlar çalışmaya devam eder. Uyuşmazlıkta agent.log, sunucunun sunduğu zincirin pin'lerini konumlarıyla listeler: chain_leaf_pin değerini Settings → Sertifikalar'daki SPKI pin'iyle karşılaştırın, config.json içindeki pins'i düzeltin (ya da MSI'yı PINS= ile yeniden kurun) ve ArcerisAgent servisini yeniden başlatın.
  4. 409 / identity_conflict: sunucu makineyi başka bir kimlik altında tutuyorsa (ör. machine.json silindikten sonra) kayıt 409 yanıtlar; makine durumu identity_conflict görünür ve kayıt saatlik olarak yeniden denenir. Yönetici olarak Makineler sayfasında "Kimliği sıfırla" ile eski kimliği temizleyin — gerçek makine hemen yeniden kaydolabilir (Bölüm 13).

Helper "other_instance" — Helper Portu Başka Bir Süreçte

Belirti: Kullanıcı oturumu other_instance durumunda bekliyor; Makineler detayındaki oturum satırı "port PID N tarafından tutuluyor" diyor ya da helper sağlığı belirsiz.

Teşhis ve çözüm:

  1. Makineler → makine detayı → oturum ölçümü satırı, helper portunu tutan süreci PID'si ve görüntü adıyla (ör. arceris-dev.exe) adlandırır; servisin devraldığı sağlıklı helper "devralındı" rozetiyle görünür (Bölüm 13).
  2. Kullanıcı tarafında arceris-dev status ve arceris-dev doctor servisin bildirdiğini yansıtır: Helper: healthy (adopted by the service, pid=N) ya da Helper: other_instance — holder pid=N; holder image=arceris-dev.exe; doctor ne yapılacağını da söyler (bekleyin, daemon stop + daemon start, ya da adı geçen süreci sonlandırın). Okunamayan rapor "state unknown" görünür; tahmin yürütülmez.
  3. Servis yeniden başlatması oturumu artık 5 dakika other_instance'ta bekletmez: servisin kendi imajını, oturum kullanıcısı olarak çalıştıran sağ kalan helper devralınır ve oturum ilk geçişte sağlıklı sayılır.
  4. Ölçülebilen bir port tutucu artık kör bir 5 dakikalık beklemeye yol açmaz: tutucu her geçişte kendi portundan yeniden ölçülür; portu başka bir süreç tuttuğunda ya da artık kimse tutmadığında (üst üste iki geçiş) helper başlatılır — bölüm başına en fazla üç erken başlatma, sonrasında 5 dakikalık retry. Bu yol hiçbir süreci sonlandırmaz.
  5. Helper'ın sağlık kaynağı değiştiğinde (pac_json / daemon.json) agent: helper health source INFO satırı yazılır. Sistem proxy'si olmayan kullanıcılarda doctor artık servisi haksız yere "erişilemez" raporlamaz. CLI komutlarının tamamı Bölüm 24'tedir.

Windows: Her Yeni PowerShell Penceresinde Güvenlik Hatası

Belirti: Kullanıcı her yeni PowerShell penceresinde kırmızı bir güvenlik hatası görüyor. Makinede Execution Policy Restricted/AllSigned ve kurulum bir GPO/oturum açma script'inden powershell -ExecutionPolicy Bypass ile çalıştırılmış.

Neden ve çözüm:

  1. Eski sürümler, script'in geçici Bypass ayarını okuyup yönetilen bloğu PowerShell profiline yazıyordu; kalıcı politika Restricted kaldığı için her yeni pencere hata veriyordu. Artık arceris-dev setup bu makinelerde profili yazmaz; ölçüm yeni bir pencerenin göreceği politika üzerinden yapılır (Documents klasörü yönlendirilmiş makinelerdeki profil yolları da kapsanır).
  2. Daha önce yazılmış blok, bir sonraki setup'ta ve helper başlangıcında kaldırılır (dosyada yalnızca o blok kaldıysa dosyanın kendisi silinir).
  3. arceris-dev doctor durumu gösterir. Filo duruşunda shell_env, Windows'ta profil bloğu olmamakla birlikte kalıcı HTTPS_PROXY bu broker'ı geçerli bir token'la gösteriyorsa ok sayılır (eskiden missing).

Windows: Helper Oturum Dizinini Okuyamıyor

Belirti: C:\ProgramData\Arceris\sessions\<SID> dizini yalnız admin erişimine açık kalmış; helper kendi dizinini okuyamıyor, servise güvenmiyor ve PAC broker'da tutuluyor.

Çözüm: Bu kilitli biçim, eski bir Arceris Agent kaldırmasından kalma bilinen bir kalıntıdır (eski kaldırıcı cred-state.json'ı tanımıyordu). Güncel servis, kullanıcının bir sonraki oturum başlangıcında dizini tam bu şekilde bulursa otomatik onarır: bilinen bayat dosyalar kaldırılır, kullanıcının erişimi — dizin içindeki hiçbir dosya değiştirilmeden — geri verilir. Elle izin düzeltmeye gerek yoktur; ajan sürümü eskiyse güncelleme (Bölüm 24) sorunu çözer.

Dev CLI / Kayıtlı Cihaz Sorunları

  1. Kullanıcı tarafında arceris-dev doctor komutunu çalıştırın; sağlık kontrolü sonucunu inceleyin (Bölüm 24).
  2. arceris-dev status kayıt durumunu ve broker sağlığını gösterir; arceris-dev daemon-info daemon durumunu iki kaynaktan (çalışan süreç ve disk) raporlar ve kaynaklar ayrılırsa uyarır.
  3. Kayıtlı Cihazlar sayfasında (/admin/enrolled-devices) cihazın active rozetiyle göründüğünü kontrol edin. expired rozeti proxy token son kullanma tarihinin geçtiğini gösterir (Bölüm 13).
  4. İptal edilip yeniden kaydedilen bir cihaz artık süreci öldürmeden kurtarılır: Kerberos önce kendini onarır; ardından her kimlik doğrulama yöntemi için çalışan credstore izleyicisi, bant dışı yeniden kaydı saniyeler içinde benimser.
  5. Sorun çözülemezse kullanıcı tarafında arceris-dev logout yapıp yeniden enroll edin; eski cihaz kaydı iptal edilir (revoke).