Nginx Real IP Yapılandırması: Proxy/CDN Arkasında Gerçek Ziyaretçi IP Alma

Son Güncelleme: Haziran 2026

Nginx Real IP yapılandırması, CDN, reverse proxy, load balancer veya güvenlik duvarı arkasında çalışan web sitelerinde gerçek ziyaretçi IP adresini doğru şekilde görmek için kritik bir ayardır. Yanlış yapılandırılmış bir sistemde tüm ziyaretçiler proxy sunucusunun IP adresinden geliyormuş gibi görünür; bu durum log analizi, güvenlik filtreleme, rate limiting ve uygulama tarafı IP kontrollerinde hatalara yol açabilir.

Bu rehberde Nginx üzerinde ngx_http_realip_module kullanarak gerçek istemci IP adresinin nasıl alınacağını, hangi başlıkların güvenilir kabul edilmesi gerektiğini, güvenlik risklerini ve pratik test adımlarını detaylı şekilde inceleyeceğiz.

İçindekiler

• Real IP Nedir ve Neden Gereklidir?
• Proxy Arkasında IP Sorunu Nasıl Oluşur?
• Nginx Real IP Modülü Nasıl Çalışır?
• Temel Nginx Real IP Yapılandırması
• CDN ve Load Balancer Senaryoları
• Loglama ve Uygulama Entegrasyonu
• Güvenlik ve En İyi Uygulamalar
• Test ve Sorun Giderme
• Sıkça Sorulan Sorular
• Sonuç

Real IP Nedir ve Neden Gereklidir?

Real IP, web sunucusuna gelen isteğin arkasındaki gerçek istemci IP adresini ifade eder. Normal şartlarda bir ziyaretçi web sitenize doğrudan bağlandığında Nginx erişim kayıtlarında ziyaretçinin IP adresi görünür. Ancak araya CDN yani içerik dağıtım ağı, reverse proxy yani ters vekil sunucu, load balancer yani yük dengeleyici veya WAF yani web uygulama güvenlik duvarı girdiğinde web sunucusu isteği doğrudan kullanıcıdan değil, bu ara katmandan alır.

Bu durumda Nginx için istemci IP adresi çoğu zaman CDN ya da proxy sunucusunun IP adresidir. Eğer doğru Real IP yapılandırması yapılmazsa sunucu loglarında binlerce farklı ziyaretçi yerine birkaç proxy IP adresi görünür. Bu yalnızca istatistiksel bir problem değildir; güvenlik, performans ve erişim kontrolü açısından da ciddi sonuçlar doğurabilir.

Gerçek IP adresine ihtiyaç duyulan durumlar

• Güvenlik analizi: Brute force, spam, bot trafiği ve şüpheli istekleri doğru IP adresi üzerinden tespit etmek için gereklidir.
• Rate limiting: Hız sınırlandırma kurallarının tüm kullanıcıları tek bir proxy IP üzerinden engellememesi için gerçek istemci IP kullanılmalıdır.
• Uygulama erişim kontrolü: Yönetim paneli, API veya özel alanlara IP bazlı izin veriliyorsa gerçek IP hatasız iletilmelidir.
• Log raporlama: Web analitiği, güvenlik denetimi ve olay müdahalesi için doğru log kayıtları kritik öneme sahiptir.
• Coğrafi yönlendirme: Kullanıcının ülkesine veya bölgesine göre içerik sunan sistemlerde doğru IP bilgisi gerekir.

Özellikle yüksek trafikli web sitelerinde, e-ticaret projelerinde, API servislerinde ve kurumsal uygulamalarda Real IP yapılandırması temel sunucu kurulum adımlarından biri olarak değerlendirilmelidir.

Proxy Arkasında IP Sorunu Nasıl Oluşur?

Bir kullanıcı web sitenize doğrudan bağlandığında bağlantı zinciri basittir: kullanıcı isteği gönderir, Nginx isteği alır ve uygulamaya iletir. Ancak CDN veya ters proxy kullanımında zincir değişir. Kullanıcı önce ara katmana bağlanır, ara katman isteği sunucuya iletir. Bu nedenle Nginx bağlantının kaynak adresi olarak kullanıcının cihazını değil, ara katmanın IP adresini görür.

Bu sorunu çözmek için proxy katmanları genellikle HTTP başlıkları üzerinden gerçek istemci IP adresini origin sunucuya aktarır. En yaygın başlıklar X-Forwarded-For, X-Real-IP ve bazı CDN sağlayıcılarına özel istemci IP başlıklarıdır. Fakat bu başlıklar dikkatli kullanılmalıdır; çünkü istemci tarafında da sahte HTTP başlıkları gönderilebilir.

Yanlış yapılandırmanın etkileri

Bu nedenle Nginx Real IP ayarı yalnızca performans veya raporlama amacıyla değil, sunucu güvenliği ve operasyonel süreklilik için de önemlidir.

Nginx Real IP Modülü Nasıl Çalışır?

Nginx üzerinde gerçek IP adresini almak için genellikle ngx_http_realip_module kullanılır. Bu modül, yalnızca güvenilir kabul edilen proxy IP adreslerinden gelen isteklerde belirli HTTP başlığını okuyarak istemci IP adresini değiştirir. Böylece Nginx değişkenleri ve log formatları gerçek ziyaretçi IP adresini kullanabilir.

Modülün temel mantığı üç parçadan oluşur: hangi proxy IP adreslerinin güvenilir olduğu, gerçek IP bilgisinin hangi başlıktan okunacağı ve zincirli proxy durumunda hangi IP adresinin seçileceği.

Temel direktifler

• set_real_ip_from: Güvenilir proxy, CDN veya load balancer IP adreslerini tanımlar. Sadece bu kaynaklardan gelen başlıklar dikkate alınmalıdır.
• real_ip_header: Gerçek IP bilgisinin okunacağı HTTP başlığını belirtir. Örneğin X-Forwarded-For veya X-Real-IP.
• real_ip_recursive: Birden fazla proxy bulunan zincirlerde doğru istemci IP adresini seçmek için kullanılır.

Bu direktiflerin yanlış kullanımı güvenlik açığına neden olabilir. Örneğin tüm interneti güvenilir proxy gibi kabul etmek, ziyaretçilerin sahte X-Forwarded-For başlığıyla kendilerini farklı IP adresinden geliyormuş gibi göstermesine izin verir. Bu nedenle set_real_ip_from alanında yalnızca gerçekten kontrol ettiğiniz veya güvendiğiniz proxy ağları yer almalıdır.

Modülün sunucuda mevcut olup olmadığını kontrol etme

Birçok modern Nginx paketinde Real IP modülü yerleşik olarak bulunur. Yine de kontrol etmek için aşağıdaki komutu kullanabilirsiniz:

nginx -V 2>&1 | grep --color=auto realip

Çıktıda --with-http_realip_module ifadesi görünüyorsa modül kullanılabilir durumdadır. Eğer özel derlenmiş bir Nginx kullanıyorsanız modülün dahil edilmediği durumlarla karşılaşabilirsiniz. Bu durumda dağıtım paketleriyle gelen standart Nginx sürümünü kullanmak veya Nginx'i ilgili modülle yeniden derlemek gerekebilir.

Temel Nginx Real IP Yapılandırması

Real IP yapılandırması genellikle http, server veya location bloğu içinde yapılabilir. En sağlıklı yöntem, tüm sanal hostları etkileyen ortak proxy kurallarını http seviyesinde tanımlamak; özel ihtiyaçları olan siteler için ise server seviyesinde ek düzenleme yapmaktır.

Aşağıdaki örnek, yalnızca belirli bir reverse proxy IP adresinden gelen X-Forwarded-For başlığını güvenilir kabul eder:

http {
    set_real_ip_from 10.10.10.5;
    real_ip_header X-Forwarded-For;
    real_ip_recursive on;

    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                    '$status $body_bytes_sent "$http_referer" '
                    '"$http_user_agent" "$http_x_forwarded_for"';

    access_log /var/log/nginx/access.log main;
}

Bu örnekte 10.10.10.5 sizin load balancer veya reverse proxy IP adresinizdir. Gerçek ortamda bu değeri kendi altyapınızdaki proxy IP adresiyle değiştirmelisiniz. Eğer proxy ağınız bir IP bloğu şeklindeyse CIDR formatı kullanılabilir.

Yerel ağdan gelen proxy için örnek

Örneğin Nginx sunucunuzun önünde aynı özel ağda bulunan bir HAProxy veya güvenlik cihazı varsa aşağıdaki gibi bir yapılandırma kullanılabilir:

set_real_ip_from 192.168.20.0/24;
real_ip_header X-Forwarded-For;
real_ip_recursive on;

Burada 192.168.20.0/24 ağındaki cihazlar güvenilir kabul edilir. Fakat bu ağ içinde istemci makineler de bulunuyorsa dikkatli olunmalıdır. Güvenilir proxy ağı ile kullanıcı ağı mümkün olduğunca ayrıştırılmalıdır.

Yapılandırmayı test etme ve yeniden yükleme

Nginx yapılandırmasını değiştirdikten sonra sözdizimi kontrolü yapılmalıdır. Hatalı yapılandırma doğrudan yeniden başlatılırsa web servisinde kesinti yaşanabilir.

nginx -t
systemctl reload nginx

reload işlemi, yapılandırmayı kesintisiz şekilde yeniden yükler. Ancak nginx -t başarısız olursa kesinlikle yeniden yükleme yapılmamalıdır.

CDN ve Load Balancer Senaryoları

Gerçek IP yapılandırması kullanılan mimariye göre değişir. Tek bir reverse proxy bulunan basit ortamlarda yapılandırma kolaydır. Ancak CDN, WAF, load balancer ve uygulama proxy katmanlarının birlikte kullanıldığı yapılarda IP zinciri daha karmaşık hale gelir.

Tek reverse proxy senaryosu

Bu senaryoda kullanıcı isteği önce reverse proxy sunucuya gelir, ardından Nginx origin sunucusuna iletilir. Reverse proxy genellikle X-Forwarded-For veya X-Real-IP başlığı ekler.

Kullanıcı → Reverse Proxy → Nginx Origin → Uygulama

Bu durumda Nginx üzerinde yalnızca reverse proxy IP adresi güvenilir kaynak olarak tanımlanır. En kritik nokta, Nginx origin sunucusunun internete açık olmaması veya yalnızca proxy IP adreslerinden erişime izin vermesidir.

CDN arkasında çalışan web sitesi

CDN kullanılan yapılarda kullanıcı istekleri CDN kenar sunucularından origin sunucuya aktarılır. Bu tür yapılarda CDN sağlayıcısının ilettiği gerçek IP başlığı kullanılabilir. Ancak burada iki güvenlik kuralı önemlidir: CDN IP aralıkları doğru tanımlanmalı ve origin sunucuya doğrudan erişim engellenmelidir.

CDN IP aralıkları zaman içinde değişebileceği için bunları elle yazıp unutmak uzun vadede sorun çıkarabilir. Sağlayıcınızın resmi IP listeleme mekanizması varsa düzenli güncelleme için otomasyon tercih edilmelidir. Bu otomasyon bir yapılandırma yönetim aracı, cron tabanlı betik veya dağıtım sürecine dahil edilen bir güncelleme adımı olabilir.

Load balancer ve çoklu proxy zinciri

Bazı yapılarda istek zinciri daha uzundur:

Kullanıcı → CDN → WAF → Load Balancer → Nginx → Uygulama

Bu durumda X-Forwarded-For başlığı birden fazla IP içerebilir. Genellikle zincirde ilk IP gerçek istemciye, sonraki IP adresleri ise ara proxy katmanlarına karşılık gelir. real_ip_recursive on ayarı, güvenilir proxy zincirinin geriye doğru değerlendirilmesine yardımcı olur.

Corelux altyapılarında kullanım

Projeleriniz için ölçeklenebilir bir altyapı planlıyorsanız Sanal Sunucu, yüksek kaynak ihtiyacı olan yapılar için Kiralık Sunucu ve esnek büyüme senaryoları için Bulut Sunucu seçenekleri değerlendirilebilir. Nginx Real IP yapılandırması bu altyapıların tamamında, özellikle proxy ve yük dengeleme katmanı kullanılan projelerde önemli bir adımdır.

Loglama ve Uygulama Entegrasyonu

Real IP yapılandırmasının başarılı olup olmadığını anlamanın en pratik yolu logları incelemektir. Nginx değişkenleri doğru ayarlandığında $remote_addr gerçek ziyaretçi IP adresini, $realip_remote_addr ise orijinal bağlantı adresini gösterebilir. Bu bilgiler olay analizi için birlikte kaydedilebilir.

Gelişmiş log formatı örneği

Aşağıdaki log formatı hem Nginx tarafından kabul edilen gerçek IP adresini hem de proxy tarafından iletilen ham başlığı kaydeder:

log_format realip '$remote_addr original=$realip_remote_addr '
                  'xff="$http_x_forwarded_for" '
                  'host="$host" request="$request" '
                  'status=$status bytes=$body_bytes_sent '
                  'ua="$http_user_agent"';

access_log /var/log/nginx/realip_access.log realip;

Bu yapılandırma özellikle geçiş sürecinde faydalıdır. Böylece hangi IP adresinin uygulamaya aktarıldığını ve proxy zincirinden hangi bilgilerin geldiğini aynı satırda görebilirsiniz.

PHP uygulamalarında gerçek IP

PHP tarafında birçok uygulama istemci IP adresini $_SERVER['REMOTE_ADDR'] üzerinden okur. Nginx Real IP modülü doğru yapılandırıldıysa ve PHP-FPM bağlantısı uygun şekilde iletiliyorsa uygulama tarafında doğru IP adresi görülebilir. Ancak bazı framework veya özel uygulamalar doğrudan HTTP_X_FORWARDED_FOR başlığını okuyabilir. Bu yaklaşım güvenlik açısından risklidir; çünkü uygulama katmanında güvenilir proxy kontrolü yapılmadan başlık okumak IP sahteciliğine neden olabilir.

Bu nedenle genel prensip şudur: IP doğrulaması mümkün olduğunca web sunucusu veya güvenilir proxy katmanında yapılmalı, uygulama ise normalize edilmiş istemci IP adresini kullanmalıdır.

Laravel, WordPress ve benzeri uygulamalar

Laravel, WordPress ve benzeri uygulamalar proxy arkasında çalıştırıldığında uygulama seviyesinde ek güvenilir proxy ayarları gerekebilir. Örneğin framework tarafında güvenilir proxy listesi tanımlanmazsa HTTPS algılama, URL üretimi, güvenli cookie davranışı veya IP bazlı middleware kontrollerinde tutarsızlık yaşanabilir. Sunucu tarafında Real IP doğru ayarlansa bile uygulama katmanının proxy farkındalığı ayrıca kontrol edilmelidir.

Paylaşımlı hosting veya yönetimli panel ortamlarında ise kullanıcıların Nginx ana yapılandırmasına erişimi olmayabilir. Bu tür projeler için Linux Hosting veya daha fazla kontrol gerektiren yapılarda Türkiye VDS Sunucu seçenekleri tercih edilebilir.

Güvenlik ve En İyi Uygulamalar

Nginx Real IP yapılandırması güvenlik açısından dikkatli planlanmalıdır. Temel risk, saldırganın sahte bir HTTP başlığı göndererek kendisini farklı bir IP adresinden geliyormuş gibi göstermesidir. Bu risk, set_real_ip_from direktifinin çok geniş tanımlanması veya origin sunucunun doğrudan internete açık bırakılmasıyla artar.

Güvenilir kaynakları dar tutun

set_real_ip_from 0.0.0.0/0 gibi tüm interneti güvenilir kabul eden yapılandırmalar kullanılmamalıdır. Bu tür bir ayar, saldırganların X-Forwarded-For başlığını manipüle ederek logları yanıltmasına, IP bazlı engelleri aşmasına ve güvenlik araçlarını etkisiz hale getirmesine neden olabilir.

# Hatalı ve tehlikeli örnek
set_real_ip_from 0.0.0.0/0;
real_ip_header X-Forwarded-For;

Bunun yerine yalnızca kendi load balancer IP adresiniz, özel ağınız veya kullandığınız CDN sağlayıcısının doğrulanmış IP aralıkları tanımlanmalıdır.

Origin sunucuya doğrudan erişimi kısıtlayın

CDN veya WAF arkasında çalışan bir web sitesinde origin sunucu doğrudan internete açıksa saldırganlar CDN katmanını atlayarak sunucuya istek gönderebilir. Bu durumda hem güvenlik kontrolleri devre dışı kalabilir hem de sahte IP başlıklarıyla loglar kirletilebilir.

Origin erişimini kısıtlamak için güvenlik duvarı, cloud firewall, ağ erişim listeleri veya Nginx seviyesinde IP izin kuralları kullanılabilir. Ancak Nginx seviyesindeki kısıtlama, ağ seviyesindeki filtrelemenin yerine geçmemelidir; ideal yaklaşım bağlantının sunucuya ulaşmadan önce engellenmesidir.

Rate limiting kurallarını Real IP sonrası uygulayın

Nginx üzerinde limit_req veya limit_conn kullanıyorsanız bu kuralların gerçek IP adresini temel aldığından emin olun. Aksi halde tüm ziyaretçileri aynı proxy IP adresi üzerinden sınırlayabilirsiniz.

http {
    set_real_ip_from 10.10.10.5;
    real_ip_header X-Forwarded-For;
    real_ip_recursive on;

    limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s;

    server {
        location /api/ {
            limit_req zone=api_limit burst=20 nodelay;
            proxy_pass http://backend_api;
        }
    }
}

Bu örnekte $binary_remote_addr, Real IP modülü işledikten sonra gerçek ziyaretçi IP adresini temsil edecek şekilde kullanılır. Bu sayede hız sınırı proxy IP adresine değil, kullanıcı IP adresine uygulanır.

Değişiklikleri aşamalı uygulayın

• Önce loglayın: Yeni Real IP ayarını doğrudan güvenlik kararlarında kullanmadan önce log formatına ekleyerek doğrulayın.
• Test ortamında deneyin: Production yani canlı sistem öncesinde staging ortamında CDN ve proxy zincirini test edin.
• Geri dönüş planı hazırlayın: Hatalı yapılandırma durumunda önceki Nginx konfigürasyonuna hızlıca dönebileceğinizden emin olun.
• IP listelerini güncel tutun: CDN veya güvenlik servislerinin IP aralıkları değişebilir; manuel listeler düzenli kontrol edilmelidir.
• Log bütünlüğünü koruyun: Güvenlik olaylarında ham başlıkları ve normalize edilmiş IP adresini birlikte saklamak analiz sürecini kolaylaştırır.

Test ve Sorun Giderme

Real IP yapılandırmasını tamamladıktan sonra yalnızca Nginx'in çalışıyor olması yeterli değildir. Loglarda beklenen IP adreslerinin göründüğünü, uygulama katmanının doğru IP aldığını ve güvenlik kurallarının doğru değişkenleri kullandığını test etmelisiniz.

Log üzerinden kontrol

Öncelikle erişim loglarını canlı izleyerek isteklerin hangi IP adresiyle kaydedildiğini kontrol edin:

tail -f /var/log/nginx/realip_access.log

Bir test isteği gönderdiğinizde $remote_addr alanında gerçek istemci IP adresinizin, original=$realip_remote_addr alanında ise proxy IP adresinin görünüp görünmediğine bakın.

curl ile başlık testi

Doğrudan origin sunucuya erişiminiz varsa sahte X-Forwarded-For başlığı göndererek yapılandırmayı test edebilirsiniz. Eğer origin yalnızca güvenilir proxy IP adreslerini kabul ediyorsa bu başlık dikkate alınmamalıdır.

curl -H "X-Forwarded-For: 203.0.113.10" https://example.com/

Bu testte, isteği güvenilir proxy dışından gönderiyorsanız Nginx'in sahte başlığı gerçek IP olarak kabul etmemesi gerekir. Eğer kabul ediyorsa set_real_ip_from yapılandırmanız fazla geniş tanımlanmış olabilir.

Yaygın hatalar ve çözümleri

Basit test lokasyonu oluşturma

Geçici olarak yalnızca yönetici IP adresinizden erişilebilen bir test lokasyonu oluşturarak Nginx değişkenlerini kontrol edebilirsiniz. Bu lokasyon canlı sistemde herkese açık bırakılmamalıdır.

location /realip-test {
    allow 198.51.100.25;
    deny all;
    default_type text/plain;
    return 200 "remote_addr=$remote_addr\nrealip_remote_addr=$realip_remote_addr\nxff=$http_x_forwarded_for\n";
}

Bu örnekte 198.51.100.25 yerine kendi yönetici IP adresinizi yazmalısınız. Test tamamlandıktan sonra bu lokasyon kaldırılmalı veya erişim sıkı şekilde sınırlandırılmalıdır.

Sıkça Sorulan Sorular

Sonuç

Nginx Real IP yapılandırması, modern web altyapılarında küçük görünen ancak güvenlik ve operasyon açısından büyük etkisi olan bir ayardır. CDN, reverse proxy, WAF veya load balancer arkasında çalışan sistemlerde gerçek ziyaretçi IP adresini doğru almak; log analizi, saldırı tespiti, hız sınırlandırma, erişim kontrolü ve uygulama güvenliği için vazgeçilmezdir.

Doğru yapılandırma için temel prensipler nettir: yalnızca güvenilir proxy IP adreslerini tanımlayın, gerçek IP başlığını bilinçli seçin, real_ip_recursive davranışını test edin, origin sunucuya doğrudan erişimi kısıtlayın ve loglarda hem normalize edilmiş IP adresini hem de proxy zincirini izleyin. Bu adımlar uygulandığında Nginx arkasındaki sistemler daha güvenli, daha izlenebilir ve daha yönetilebilir hale gelir.

Web projeniz için kontrollü, esnek ve ölçeklenebilir bir altyapıya ihtiyaç duyuyorsanız Corelux üzerinde Sanal Sunucu, Kiralık Sunucu, Bulut Sunucu ve SSL Sertifikası hizmetlerini değerlendirebilirsiniz. Doğru sunucu mimarisi ve doğru proxy yapılandırmasıyla hem performans hem de güvenlik tarafında daha sağlam bir temel oluşturabilirsiniz.