Cara Mengonfigurasi Sertifikat SSL di HAProxy

HAProxy adalah load balancer TCP dan HTTP yang mengakhiri TLS, sehingga ia mendekripsi lalu lintas di ujung jaringan dan meneruskan HTTP biasa ke server backend Anda. Itulah yang membuatnya menjadi satu-satunya mesin dalam jalur tersebut yang membutuhkan sertifikat, dan ia menginginkan sertifikat itu dalam bentuk tertentu: satu file, yang menyimpan sertifikat, intermediate mana pun, dan private key.

Panduan ini membahas seluruh prosesnya: membuat CSR, menyusun file PEM, menulis frontend dan backend, memeriksa konfigurasi, dan me-reload tanpa memutus koneksi yang sedang aktif. Perintah-perintah dijalankan menggunakan HAProxy 3.4, cabang long-term support yang sedang berlaku saat ini, dirilis Juni 2026 dan dipelihara hingga Q2 2031.

Apa yang diharapkan HAProxy: satu file PEM tunggal

Kebanyakan server menerima sertifikat, chain, dan key sebagai tiga pengaturan terpisah. HAProxy menerima satu saja. Manual konfigurasinya menjelaskan kata kunci crt sebagai penanda “file PEM yang berisi sertifikat yang diperlukan serta private key terkait”, yang dibangun dengan menggabungkan file-file PEM, dan menambahkan bahwa “jika CA Anda memerlukan sertifikat intermediate, ini juga dapat digabungkan ke dalam file ini”.

Ada dua perilaku yang perlu diketahui sebelum Anda memulai, karena keduanya menghemat pekerjaan nanti:

• Key dapat disimpan di samping sertifikat, bukan di dalamnya. Jika file tersebut tidak berisi private key, HAProxy akan mencari path yang sama dengan tambahan .key. Jadi mydomain.pem ditambah mydomain.pem.key berfungsi sama baiknya dengan satu file gabungan.
• Anda bisa mengarahkan crt ke sebuah direktori. HAProxy memuat setiap file yang ditemukan di sana dan memilih sertifikat yang tepat untuk setiap permintaan menggunakan SNI. Begitulah caranya menyajikan beberapa situs dari satu frontend tanpa perlu satu baris bind untuk masing-masing.

Membuat CSR dan private key

CSR adalah permintaan yang dienkode yang Anda serahkan kepada Certificate Authority. Buat CSR tersebut di mesin HAProxy, atau di mana pun Anda dapat menjaga private key tetap aman, karena key tersebut tidak pernah meninggalkan pihak Anda.

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"

Baris -addext pada praktiknya bukan opsional. Browser sudah lama berhenti mencocokkan nama host dengan Common Name dan hanya membaca Subject Alternative Name, sehingga CSR yang hanya membawa CN akan menghasilkan sertifikat yang gagal di setiap browser modern saat ini. Cantumkan setiap nama yang harus dicakup oleh sertifikat, termasuk domain polos dan bentuk www jika Anda melayani keduanya.

Hilangkan opsi -subj dan -addext jika Anda lebih suka diminta mengisi setiap kolom. Bagaimanapun caranya, Anda akan mendapatkan dua file: mydomain.csr untuk diajukan, dan mydomain.key untuk disimpan. Pastikan CSR berisi apa yang Anda harapkan sebelum mengajukannya, baik dengan CSR decoder kami atau secara lokal:

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

Periksa apakah entri SAN sudah tercantum dan tanda tangannya terverifikasi. Jika Anda lebih suka tidak menggunakan command line sama sekali, CSR generator kami menghasilkan pasangan yang sama langsung di browser. Informasi lebih lanjut tentang perintah yang mendasarinya ada di panduan kami tentang perintah OpenSSL.

Mendapatkan sertifikat yang diterbitkan

Ajukan CSR ke CA, pilih jenis sertifikat yang sesuai dengan apa yang Anda lindungi, dan selesaikan proses validasi. Sertifikat domain tunggal mencakup satu nama host, wildcard mencakup setiap subdomain tingkat pertama, dan sertifikat multi-domain (SAN) mencakup daftar nama yang tidak saling berkaitan. Di belakang load balancer, multi-domain adalah pilihan yang umum, karena satu instance HAProxy biasanya melayani beberapa situs.

CA akan mengembalikan sebuah arsip yang berisi sertifikat Anda dan chain intermediate, biasanya berupa file CA bundle. Keduanya sudah dalam format PEM, yang memang Anda perlukan. Rencanakan perpanjangan sekarang, bukan nanti: sejak 15 Maret 2026 sertifikat TLS yang tepercaya secara publik hanya dapat berlaku paling lama 200 hari, menurun menjadi 100 hari pada Maret 2027 dan 47 hari pada Maret 2029, sehingga penggantian manual akan tidak lagi praktis dalam waktu yang cukup dekat.

Membangun file PEM yang akan dibaca HAProxy

Buat direktori untuk sertifikat dan susun file di sana. Simpan semuanya di satu tempat sejak awal; memisahkan ini di antara direktori home, /etc/haproxy, dan /etc/ssl adalah cara orang akhirnya mengedit satu file sementara HAProxy membaca file yang lain.

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

Gabungkan sertifikat, lalu intermediate, lalu private key. Redirect ini harus dijalankan sebagai root, jadi salurkan (pipe) ke tee daripada menulis sudo cat ... > /etc/haproxy/certs/..., yang akan gagal dengan error izin karena shell membuka file output sebagai pengguna Anda sendiri sebelum sudo pernah dijalankan:

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

File itu sekarang berisi private key Anda dalam bentuk teks biasa, jadi kunci file tersebut sebelum melangkah lebih jauh:

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

Izin yang hanya bisa diakses root memang benar di sini, bukan sebuah rintangan. HAProxy dijalankan dengan hak akses superuser, yang menurut manualnya diperlukan agar dapat beralih ke pengguna tak berhak khususnya sendiri setelahnya, dan ia membaca sertifikat selama proses startup itu. Tidak perlu melonggarkan izin agar pengguna haproxy dapat membaca key tersebut, dan Anda memang tidak seharusnya melakukannya.

Jika Anda membuat CSR di mesin yang berbeda, salin file-file tersebut ke mesin HAProxy dulu dan hapus salinannya dari direktori transit setelahnya:

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

Mengonfigurasi HAProxy

Buka /etc/haproxy/haproxy.cfg di editor terminal pada server itu sendiri, seperti nano atau vim. Edit langsung di tempat itu daripada di workstation, sehingga Anda tidak akan pernah me-reload file yang berbeda dari yang telah Anda uji.

Frontend

Satu frontend dapat menerima baik HTTP biasa maupun HTTPS. Bind port 80 untuk redirect, bind port 443 dengan sertifikat, dan kirim sisanya ke backend:

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 menawarkan HTTP/2 dan kembali ke HTTP/1.1 jika tidak tersedia. Redirect hanya dipicu ketika permintaan tidak datang melalui TLS, yang diuji oleh ssl_fc, sehingga permintaan pada port 443 langsung diteruskan tanpa penundaan.

Letakkan semua opsi TLS pada satu baris bind itu

Di sinilah konfigurasi HAProxy paling sering salah, dan kesalahannya terjadi secara diam-diam. Panduan sering menyajikan pengerasan (hardening) TLS sebagai langkah kedua, menunjukkan baris bind baru untuk port 443 dengan opsi tambahan di dalamnya. Jika Anda menambahkan baris tersebut daripada mengedit baris yang sudah ada, Anda akan berakhir dengan dua baris bind untuk port yang sama, dan HAProxy tidak akan memberi peringatan. Ia akan mulai berjalan, dan membuka dua soket dengar (listening socket) terpisah pada port 443 dengan pengaturan TLS yang berbeda. Soket mana yang akan diterima koneksi tertentu bukanlah sesuatu yang Anda kendalikan, sehingga pengerasan Anda hanya mencakup kira-kira setengah dari lalu lintas Anda.

Pemeriksaan konfigurasi juga tidak dapat menangkap hal ini, dan dokumentasinya sendiri menjelaskan alasannya: -c “hanya melakukan pemeriksaan file konfigurasi dan keluar sebelum mencoba melakukan bind“. Listener duplikat adalah kondisi yang terjadi pada saat binding, jadi pemeriksaan sintaks tidak akan pernah melihatnya.

Tetapkan default global sebagai gantinya, agar setiap baris bind dalam file mewarisinya dan tidak ada yang perlu diduplikasi:

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

Perlu diketahui sebelum Anda menyalin blok itu ke mana pun: ssl-min-ver sudah secara default bernilai TLSv1.2, menurut kata-kata HAProxy sendiri. Menetapkannya ke TLSv1.2 tidak mengubah apa pun dan hanya mendokumentasikan niat Anda, yang tidak masalah, tetapi itu bukan peningkatan keamanan seperti yang sering digambarkan. Dua pengaturan cipher itulah yang benar-benar berpengaruh, dan keduanya memang sengaja dipisahkan: ssl-default-bind-ciphers berlaku untuk TLS 1.2 dan versi di bawahnya, ssl-default-bind-ciphersuites berlaku untuk TLS 1.3. Tetapkan hanya yang pertama, dan suite TLS 1.3 Anda akan tetap menggunakan default-nya.

Backend

Berikan setiap server alamat yang nyata. Ini lebih penting dari yang terlihat:

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

Baris server yang ditulis seperti server web1 :80 check, dengan alamat yang dihilangkan, tidak akan memunculkan error. HAProxy menerimanya dan mengartikan alamat yang hilang tersebut sebagai 0.0.0.0, yang menurut manualnya adalah nilai khusus yang berarti koneksi diteruskan ke alamat IP yang sama dengan yang dihubungi oleh klien. Alamat itu adalah HAProxy itu sendiri, sehingga backend secara diam-diam mengarah ke port 80 milik HAProxy sendiri, yang merupakan frontend yang baru Anda konfigurasikan. Lalu lintas kembali berputar ke redirect, bukan mencapai aplikasi mana pun, dan health check terlihat sehat karena memang ada sesuatu yang mendengarkan. Jika load balancer menjawab setiap permintaan HTTPS dengan redirect ke dirinya sendiri, periksa dulu baris-baris server-nya.

Karena HAProxy mengakhiri TLS, backend menerima HTTP biasa pada port 80 dan tidak membutuhkan sertifikat sendiri. Jika kebijakan mengharuskan enkripsi juga pada tahap ini, tambahkan ssl verify required dan file CA pada baris server, dan arahkan ke port 443 sebagai gantinya.

Teruskan skema asli ke backend. Karena backend sekarang menerima HTTP biasa, aplikasi yang menghasilkan URL absolut, seperti yang dilakukan WordPress, Django, dan Rails, akan menghasilkan URL tersebut dengan http://, yang muncul sebagai konten campuran atau sebagai loop redirect yang dibuat oleh aplikasi itu sendiri. Tambahkan satu baris ke frontend:

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

dan satu ke backend, yang juga meneruskan alamat IP klien yang sebenarnya:

option forwardfor

Kebanyakan framework kemudian perlu diberi tahu agar mempercayai header-header tersebut; bagian itu dikonfigurasi di dalam aplikasi, bukan di HAProxy.

Periksa konfigurasi sebelum Anda menerapkannya

Jangan pernah restart load balancer dengan file yang belum diverifikasi. Validasi dulu:

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

Dengan -V ia akan menampilkan Configuration file is valid jika berhasil dan mengembalikan status keluar (exit status) nol. Tanpa itu, keberhasilan bersifat diam-diam. Peringatan apa pun akan dilaporkan baik file tersebut valid atau tidak, jadi baca outputnya, jangan hanya mengandalkan ketidakadaan teks merah.

Reload, bukan restart

sudo systemctl reload haproxy

Perbedaan ini nyata pada load balancer. Reload memulai proses baru dan memberi sinyal ke proses lama untuk “menyelesaikan apa yang sedang dilakukan dan kemudian keluar”, sehingga permintaan yang sudah berjalan akan selesai secara normal. Restart memberi sinyal ke proses lama untuk “berhenti seketika tanpa menyelesaikan apa yang sedang dilakukan”, yang memutus koneksi yang sedang aktif, termasuk unggahan dan panggilan API yang berjalan lama. Gunakan restart hanya ketika reload tidak dapat menerapkan perubahan, misalnya setelah mengubah pengaturan proses pada bagian global.

Pastikan layanan kembali berjalan dan mendengarkan pada kedua port:

sudo systemctl status haproxy
sudo ss -tlnp | grep haproxy

Persisnya satu soket dengar per port adalah yang Anda inginkan di sini. Dua soket pada port 443 berarti Anda memiliki baris bind duplikat seperti yang dijelaskan di atas.

Verifikasi bahwa sertifikat sedang disajikan

Periksa apa yang sebenarnya disajikan oleh HAProxy, termasuk chain-nya, dari server itu sendiri:

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

Baca bagian Certificate chain di bagian atas output. Sertifikat Anda seharusnya muncul di depth 0 dan intermediate di depth 1. Jika depth 1 tidak ada, berarti intermediate tidak pernah masuk ke dalam file PEM, dan situs akan berfungsi di beberapa browser tetapi gagal di browser lain. Abaikan baris Verify return code saat menilai hal ini: baris itu hanya melaporkan hasil verifikasi chain, dan dapat terbaca sebagai berhasil dalam situasi yang sama sekali tidak berhubungan dengan apa yang sedang Anda uji.

Lalu konfirmasi dari luar, di mana hasilnya mencerminkan apa yang benar-benar didapatkan oleh pengunjung nyata. SSL Checker kami melaporkan sertifikat, chain, dan tanggal kedaluwarsanya.

Perpanjangan dan otomatisasi

Mengganti file PEM adalah seluruh prosedur perpanjangan: bangun ulang file tersebut dari sertifikat baru dan key yang sama atau yang baru, lalu reload. Tidak ada apa pun dalam konfigurasi HAProxy yang merujuk pada tanggal kedaluwarsa, sehingga tidak perlu ada perubahan konfigurasi selama path file tetap sama.

Dengan masa berlaku sertifikat yang semakin singkat, otomatisasi patut disiapkan sekarang. HAProxy mendapatkan klien ACME bawaan (built-in) pada versi 3.2, yang dikonfigurasi melalui bagian acme. Perlakukan ini sebagai pratinjau, bukan infrastruktur produksi, untuk saat ini: fitur ini masih ditandai sebagai eksperimental di 3.4 dan memerlukan expose-experimental-directives di bagian global, hanya mendukung jenis challenge http-01, dns-01, dan dns-persist-01, dan sertifikat yang dihasilkannya harus di-dump dari stats socket untuk mencapai disk. Jenis dns-persist-01, yang ditambahkan di 3.4, menggunakan rekaman TXT statis yang ditetapkan sekali dan tidak pernah berubah di antara perpanjangan, sehingga tidak membutuhkan akses tulis ke API penyedia DNS pada setiap perpanjangan. Alternatif yang sudah mapan adalah menjalankan klien ACME eksternal dan membiarkan langkah deploy-nya membangun ulang file PEM dan me-reload HAProxy, yang merupakan pola yang sama seperti yang dijelaskan dalam panduan ACME kami untuk Apache dan NGINX.

Pertanyaan yang Sering Diajukan

Jika sertifikat sudah terpasang tetapi browser masih memunculkan keluhan, panduan kami tentang error SSL yang umum terjadi membahas penyebab-penyebab yang biasa muncul, paling sering berupa chain yang tidak lengkap atau nama yang tidak tercantum dalam sertifikat.