HAProxy’de SSL Sertifikası Nasıl Yapılandırılır

HAProxy, TLS’i sonlandıran bir TCP ve HTTP yük dengeleyicisidir; yani trafiği kenar noktada şifresini çözer ve düz HTTP olarak arka uç sunucularınıza iletir. Bu da onu yol üzerinde sertifikaya ihtiyaç duyan tek makine haline getirir ve o sertifikayı belirli bir biçimde ister: sertifikayı, varsa ara sertifikaları ve özel anahtarı içeren tek bir dosya.

Bu kılavuz tüm süreci kapsar: bir CSR oluşturmak, PEM dosyasını bir araya getirmek, frontend ve backend’i yazmak, yapılandırmayı kontrol etmek ve canlı bağlantıları kesmeden yeniden yüklemek. Komutlar, Haziran 2026’da yayınlanan ve 2031’in 2. çeyreğine kadar desteklenen mevcut uzun vadeli destek dalı olan HAProxy 3.4 üzerinde çalıştırılmıştır.

HAProxy’nin beklediği şey: tek bir PEM dosyası

Çoğu sunucu, sertifikayı, zinciri ve anahtarı üç ayrı ayar olarak alır. HAProxy tek bir ayar alır. Yapılandırma kılavuzu, crt anahtar kelimesini “gerekli sertifikaları ve ilgili özel anahtarları içeren bir PEM dosyası” olarak tanımlar; bu dosya PEM dosyalarının birleştirilmesiyle oluşturulur ve “CA’nız bir ara sertifika gerektiriyorsa, bu da bu dosyaya birleştirilebilir” der.

Başlamadan önce bilinmesi gereken iki davranış vardır, çünkü bunlar daha sonra iş yükünüzü azaltır:

• Anahtar, sertifikanın içinde değil yanında bulunabilir. Dosyada özel anahtar yoksa, HAProxy sonuna .key eklenmiş aynı yolu arar. Yani mydomain.pem ile mydomain.pem.key birlikte kullanıldığında, tek bir birleşik dosya kadar iyi çalışır.
• crt ifadesini bir dizine yönlendirebilirsiniz. HAProxy orada bulduğu her dosyayı yükler ve SNI kullanarak her istek için doğru sertifikayı seçer. Tek bir frontend üzerinden, her biri için ayrı bir bind satırı yazmadan birden fazla siteyi bu şekilde sunabilirsiniz.

CSR ve özel anahtarı oluşturun

Bir CSR, Sertifika Otoritesi‘ne teslim ettiğiniz kodlanmış istektir. Bunu HAProxy makinesinde ya da özel anahtarı güvende tutabileceğiniz herhangi bir yerde oluşturun, çünkü anahtar sizin tarafınızdan hiçbir zaman ayrılmaz.

openssl req -new -newkey rsa:2048 -nodes 
  -keyout mydomain.key -out mydomain.csr 
  -subj "/C=US/ST=California/L=San Jose/O=Your Company/CN=mydomain.com" 
  -addext "subjectAltName=DNS:mydomain.com,DNS:www.mydomain.com"

-addext satırı pratikte isteğe bağlı değildir. Tarayıcılar yıllar önce ana bilgisayar adlarını Common Name ile eşleştirmeyi bıraktı ve yalnızca Subject Alternative Name’i okuyor; bu yüzden yalnızca CN içeren bir CSR, mevcut her tarayıcıda başarısız olan bir sertifika üretir. Sertifikanın kapsaması gereken her adı listeleyin; hem sade alan adını hem de her ikisini de sunuyorsanız www biçimini ekleyin.

Her alan için ayrı ayrı bilgi girmek isterseniz -subj ve -addext seçeneklerini kaldırın. Her iki durumda da elinizde iki dosya kalır: göndereceğiniz mydomain.csr ve saklayacağınız mydomain.key. Göndermeden önce CSR’ın beklediğiniz bilgileri içerdiğini CSR çözücümüz ile ya da yerel olarak doğrulayın:

openssl req -noout -text -verify -in mydomain.csr

SAN girişlerinin listelendiğini ve imzanın doğrulandığını kontrol edin. Komut satırını hiç kullanmak istemiyorsanız, CSR oluşturucumuz aynı çifti tarayıcıda üretir. Altta yatan komutlar hakkında daha fazla bilgi için OpenSSL komutları rehberimize bakabilirsiniz.

Sertifikayı düzenletin

CSR’ı CA’ya gönderin, korumak istediğiniz şeye uygun sertifika türünü seçin ve doğrulamayı tamamlayın. Tek alan adlı bir sertifika bir ana bilgisayar adını kapsar, bir wildcard her birinci seviye alt alan adını kapsar ve bir çoklu alan adı (SAN) sertifikası birbiriyle ilgisiz bir isim listesini kapsar. Bir yük dengeleyicinin arkasında çoklu alan adı yaygın bir tercihtir, çünkü tek bir HAProxy örneği genellikle birden fazla siteyi önden karşılar.

CA, sertifikanızı ve ara zinciri içeren bir arşivi, genellikle bir CA paketi dosyası olarak döndürür. Her ikisi de zaten ihtiyacınız olan PEM formatındadır. Yenilemeyi şimdiden planlayın, daha sonraya bırakmayın: 15 Mart 2026 itibarıyla, kamuya güvenilen bir TLS sertifikası en fazla 200 gün geçerli olabilir; bu süre Mart 2027’de 100 güne, Mart 2029’da ise 47 güne düşecektir, dolayısıyla manuel değiştirme yakında pratik olmaktan çıkacaktır.

HAProxy’nin okuyacağı PEM dosyasını oluşturun

Sertifikalar için bir dizin oluşturun ve dosyayı orada bir araya getirin. Baştan itibaren her şeyi tek bir yerde tutun; bunu bir ana dizin, /etc/haproxy ve /etc/ssl arasında bölmek, insanların bir dosyayı düzenlerken HAProxy’nin başka bir dosyayı okumasına yol açan tipik durumdur.

sudo mkdir -p /etc/haproxy/certs
sudo chmod 700 /etc/haproxy/certs

Sertifikayı, ardından ara sertifikaları, ardından özel anahtarı birleştirin. Yönlendirme root olarak çalışmalıdır, bu yüzden sudo cat ... > /etc/haproxy/certs/... yazmak yerine tee‘ye yönlendirin; ilk yöntem, kabuk çıktı dosyasını sudo çalışmadan önce kendi kullanıcınız olarak açtığı için izin hatası verir:

cat mydomain.crt intermediate.crt mydomain.key 
  | sudo tee /etc/haproxy/certs/mydomain.pem > /dev/null

Bu dosya artık özel anahtarınızı düz metin olarak içeriyor, bu yüzden devam etmeden önce erişimi kısıtlayın:

sudo chown root:root /etc/haproxy/certs/mydomain.pem
sudo chmod 600 /etc/haproxy/certs/mydomain.pem

Sadece root’un erişebilmesi burada engel değil, doğru olan yaklaşımdır. HAProxy süper kullanıcı yetkileriyle başlatılır; kılavuzu, bunun daha sonra kendi ayrıcalıksız kullanıcısına geçebilmesi için gerekli olduğunu belirtir ve sertifikayı bu başlangıç sırasında okur. haproxy kullanıcısının anahtarı okuyabilmesi için izinleri genişletmeye gerek yoktur ve bunu yapmamalısınız.

CSR’ı farklı bir makinede oluşturduysanız, dosyaları önce karşıya kopyalayın ve ardından geçici dizindeki kopyaları silin:

scp mydomain.crt intermediate.crt mydomain.key sysadmin@haproxy-server:/home/sysadmin/

HAProxy’yi yapılandırın

Sunucunun kendisinde nano ya da vim gibi bir terminal düzenleyicisinde /etc/haproxy/haproxy.cfg dosyasını açın. Bunu bir iş istasyonunda değil, doğrudan üzerinde düzenleyin; böylece test ettiğiniz dosyadan farklı bir dosyayı asla yeniden yüklemezsiniz.

Frontend

Tek bir frontend hem düz HTTP hem de HTTPS’i kabul edebilir. Yönlendirme için 80 portunu bağlayın, sertifikayla 443 portunu bağlayın ve geri kalan her şeyi backend’e gönderin:

frontend web_frontend
    mode http
    bind *:80
    bind *:443 ssl crt /etc/haproxy/certs/mydomain.pem alpn h2,http/1.1

    http-request redirect scheme https code 301 unless { ssl_fc }

    default_backend web_servers

alpn h2,http/1.1 HTTP/2 sunar ve gerekirse HTTP/1.1’e geri döner. Yönlendirme yalnızca istek TLS üzerinden gelmediğinde tetiklenir; bunu ssl_fc test eder, dolayısıyla 443 portundaki istekler doğrudan geçer.

Tüm TLS seçeneklerini o tek bind satırına koyun

HAProxy yapılandırmalarının en sık yanlış gittiği yer burasıdır ve hata sessizce oluşur. Rehberler genellikle TLS sertleştirmesini ikinci bir adım olarak sunar ve 443 portu için ekstra seçenekler içeren yeni bir bind satırı gösterir. Mevcut satırı düzenlemek yerine bu satırı eklerseniz, aynı port için iki bind satırınız olur ve HAProxy bundan şikayet etmez. Başlar ve 443 portunda farklı TLS ayarlarına sahip iki ayrı dinleme soketi açar. Belirli bir bağlantının hangi sokete düşeceği sizin kontrolünüzde değildir, bu yüzden sertleştirmeniz trafiğinizin yaklaşık yarısını kapsar.

Yapılandırma denetimi de bunu yakalamaz ve kendi belgesi bunun nedenini açıklar: -c “yalnızca yapılandırma dosyalarının bir denetimini gerçekleştirir ve bağlama denemesinden önce çıkar”. Yinelenen bir dinleyici, bağlama zamanında ortaya çıkan bir durumdur, dolayısıyla bir söz dizimi denetimi bunu asla göremez.

Bunun yerine genel varsayılanlar ayarlayın; böylece dosyadaki her bind satırı bunları devralır ve yinelenecek bir şey kalmaz:

global
    ssl-default-bind-options ssl-min-ver TLSv1.2 prefer-client-ciphers
    ssl-default-bind-ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305
    ssl-default-bind-ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256

Bu bloğu herhangi bir yere kopyalamadan önce bilinmesi gereken şey: ssl-min-ver zaten HAProxy’nin kendi ifadesiyle varsayılan olarak TLSv1.2 değerine sahiptir. Bunu TLSv1.2 olarak ayarlamak hiçbir şeyi değiştirmez ve sadece niyeti belgeler; bu iyi bir şeydir ama sıklıkla sunulduğu gibi bir güvenlik iyileştirmesi değildir. Gerçek işi iki şifreleme ayarı yapar ve bunlar kasıtlı olarak ayrıdır: ssl-default-bind-ciphers TLS 1.2 ve altına uygulanır, ssl-default-bind-ciphersuites TLS 1.3’e uygulanır. Yalnızca ilkini ayarlarsanız, TLS 1.3 paketleriniz varsayılan değerlerinde kalır.

Backend

Her sunucuya gerçek bir adres verin. Bu, göründüğünden çok daha önemlidir:

backend web_servers
    mode http
    balance roundrobin
    option httpchk GET /
    server web1 10.0.0.11:80 check
    server web2 10.0.0.12:80 check

Adresi belirtilmeden server web1 :80 check şeklinde yazılan bir sunucu satırı hata vermez. HAProxy bunu kabul eder ve eksik adresi 0.0.0.0 olarak çözer; kılavuzu bunu, bağlantının istemcinin bağlandığı aynı IP adresine iletildiği anlamına gelen özel bir değer olarak ele alır. O adres HAProxy’nin kendisidir, dolayısıyla backend sessizce HAProxy’nin kendi 80 portuna işaret eder, bu da az önce yapılandırdığınız frontend’dir. Trafik herhangi bir uygulamaya ulaşmak yerine yönlendirmeye geri döner ve sağlık kontrolleri sağlıklı görünür çünkü orada gerçekten bir şey dinlemektedir. Bir yük dengeleyici her HTTPS isteğine kendisine yönlendirme ile yanıt veriyorsa, önce sunucu satırlarını kontrol edin.

HAProxy TLS’i sonlandırdığından, backend’ler 80 portunda düz HTTP alır ve kendi sertifikalarına ihtiyaç duymaz. Politika bu bacakta da şifreleme gerektiriyorsa, sunucu satırlarına ssl verify required ve bir CA dosyası ekleyin ve bunları 443 portuna yönlendirin.

Orijinal şemayı backend’e iletin. Backend artık düz HTTP aldığından, WordPress, Django ve Rails gibi mutlak URL’ler üreten bir uygulama bunları http:// ile üretecektir; bu da karışık içerik olarak ya da uygulamanın kendi yarattığı bir yönlendirme döngüsü olarak ortaya çıkar. Frontend’e bir satır ekleyin:

http-request set-header X-Forwarded-Proto https if { ssl_fc }

ve gerçek istemci IP adresini de ileten şu satırı backend’e ekleyin:

option forwardfor

Çoğu framework’ün ardından bu başlıklara güvenmesi söylenmelidir; bu kısım HAProxy’de değil, uygulamada yapılandırılır.

Uygulamadan önce yapılandırmayı kontrol edin

Doğrulanmamış bir dosyayla bir yük dengeleyiciyi asla yeniden başlatmayın. Önce doğrulayın:

sudo haproxy -c -V -f /etc/haproxy/haproxy.cfg

-V ile başarılı olduğunda Configuration file is valid yazdırır ve çıkış durumu sıfır döndürür. Onsuz, başarı sessizdir. Herhangi bir uyarı, dosya geçerli olsun ya da olmasın raporlanır, bu yüzden kırmızı metin olmamasına güvenmek yerine çıktıyı okuyun.

Yeniden başlatmak yerine yeniden yükleyin

sudo systemctl reload haproxy

Bir yük dengeleyicide bu ayrım gerçektir. Yeniden yükleme yeni bir işlem başlatır ve eskisine “yaptıklarını bitirip çıkması” için sinyal gönderir, böylece halihazırda devam eden istekler normal şekilde tamamlanır. Yeniden başlatma ise eski işleme “yaptıklarını bitirmeden hemen sonlanması” için sinyal gönderir, bu da yüklemeler ve uzun süren API çağrıları dahil canlı bağlantıları keser. Yeniden başlatmayı yalnızca bir yeniden yüklemenin değişikliği alamayacağı durumlarda kullanın; örneğin global bölümdeki işlem ayarlarını değiştirdikten sonra.

Servisin geri döndüğünü ve her iki portu da dinlediğini doğrulayın:

sudo systemctl status haproxy
sudo ss -tlnp | grep haproxy

Burada istediğiniz şey, her port için tam olarak bir dinleme soketidir. 443 portunda iki tane varsa, yukarıda açıklanan yinelenen bind satırına sahipsiniz demektir.

Sertifikanın sunulduğunu doğrulayın

Sunucunun kendisinden, HAProxy’nin gerçekte sunduğu şeyi, zincir dahil, kontrol edin:

openssl s_client -connect mydomain.com:443 -servername mydomain.com < /dev/null

Çıktının üst kısmındaki Certificate chain bölümünü okuyun. Sertifikanız derinlik 0’da, ara sertifika ise derinlik 1’de görünmelidir. Derinlik 1 eksikse, ara sertifika PEM dosyasına hiç girmemiştir ve site bazı tarayıcılarda çalışırken diğerlerinde başarısız olacaktır. Bunu değerlendirirken Verify return code satırını göz ardı edin: bu yalnızca zincir sonucunu raporlar ve test ettiğinizle ilgisi olmayan durumlarda bile başarılı görünebilir.

Ardından sonucun gerçek ziyaretçilerin aldığını yansıttığı dışarıdan da doğrulayın. SSL Checker‘ımız sertifikayı, zinciri ve son kullanma tarihini raporlar.

Yenilemeler ve otomasyon

PEM dosyasını değiştirmek, yenileme prosedürünün tamamıdır: yeni sertifika ve aynı ya da yeni bir anahtardan yeniden oluşturun, ardından yeniden yükleyin. HAProxy yapılandırmasında son kullanma tarihine atıfta bulunan hiçbir şey yoktur, dolayısıyla dosya yolu aynı kaldığı sürece herhangi bir yapılandırma düzenlemesine gerek yoktur.

Sertifika ömürleri kısaldıkça, otomasyonu şimdiden kurmaya değer. HAProxy, 3.2 sürümünde bir acme bölümü aracılığıyla yapılandırılan yerleşik bir ACME istemcisi kazandı. Bunu şimdilik üretim altyapısı yerine bir önizleme olarak değerlendirin: 3.4’te hâlâ deneysel olarak işaretlenmiştir ve global bölümde expose-experimental-directives gerektirir, yalnızca http-01, dns-01 ve dns-persist-01 doğrulama türlerini destekler ve oluşturduğu sertifikaların diske ulaşması için stats soketinden dökülmesi gerekir. 3.4’te eklenen dns-persist-01 türü, bir kez ayarlanan ve yenilemeler arasında hiç değişmeyen statik bir TXT kaydı kullanır, bu yüzden her yenilemede DNS sağlayıcı API’sine yazma erişimi gerektirmez. Yerleşik alternatif, harici bir ACME istemcisi çalıştırmak ve dağıtım adımının PEM dosyasını yeniden oluşturup HAProxy’yi yeniden yüklemesini sağlamaktır; bu, Apache ve NGINX için ACME rehberimizde anlatılan aynı örüntüdür.

Sıkça Sorulan Sorular

Sertifika kurulu olduğu halde tarayıcılar hâlâ şikayet ediyorsa, yaygın SSL hataları rehberimiz, en sık görülen nedenleri kapsar; bunlar genellikle eksik bir zincir ya da sertifikanın listelemediği bir isimdir.