Cum se configurează un certificat SSL în HAProxy

HAProxy este un balansor de sarcină TCP și HTTP care termină TLS, deci decriptează traficul la margine și transmite HTTP simplu către serverele dvs. backend. Acest lucru îl face singura mașină de pe traseu care are nevoie de certificat, iar acesta dorește certificatul într-o formă specifică: un singur fișier, care conține certificatul, orice intermediari și cheia privată.

Acest ghid acoperă întregul traseu: generarea unui CSR, asamblarea fișierului PEM, scrierea frontend-ului și backend-ului, verificarea configurației și reîncărcarea fără a întrerupe conexiunile active. Comenzile au fost rulate pe HAProxy 3.4, ramura curentă cu suport pe termen lung, lansată în iunie 2026 și întreținută până în trimestrul 2 al anului 2031.

Ce așteaptă HAProxy: un singur fișier PEM

Majoritatea serverelor iau certificatul, lanțul și cheia ca trei setări separate. HAProxy le ia pe toate într-una singură. Manualul său de configurare descrie cuvântul cheie crt ca desemnând „un fișier PEM care conține atât certificatele necesare, cât și orice chei private asociate”, construit prin concatenarea fișierelor PEM, și adaugă că „dacă CA-ul dvs. necesită un certificat intermediar, acesta poate fi de asemenea concatenat în acest fișier”.

Merită să cunoașteți două comportamente înainte de a începe, deoarece economisesc muncă mai târziu:

• Cheia poate exista alături de certificat, nu neapărat în interiorul lui. Dacă fișierul nu conține o cheie privată, HAProxy caută aceeași cale cu .key adăugat. Astfel, mydomain.pem plus mydomain.pem.key funcționează la fel de bine ca un singur fișier combinat.
• Puteți indica crt către un director. HAProxy încarcă fiecare fișier găsit acolo și selectează certificatul potrivit pentru fiecare cerere folosind SNI. Așa puteți servi mai multe site-uri dintr-un singur frontend fără câte o linie bind pentru fiecare.

Generați CSR-ul și cheia privată

Un CSR este cererea codificată pe care o predați Autorității de Certificare. Generați-l pe mașina HAProxy sau oriunde puteți păstra cheia privată în siguranță, întrucât cheia nu părăsește niciodată partea dvs.

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"

Linia -addext nu este opțională în practică. Browserele au încetat să mai potrivească numele gazdelor cu Common Name de ani de zile și citesc doar Subject Alternative Name, astfel încât un CSR care conține doar un CN produce un certificat care eșuează în orice browser actual. Enumerați fiecare nume pe care certificatul trebuie să-l acopere, inclusiv domeniul simplu și forma www dacă serviți ambele.

Omiteți opțiunile -subj și -addext dacă preferați să fiți întrebat pentru fiecare câmp. Oricum ar fi, veți obține două fișiere: mydomain.csr pentru a-l trimite și mydomain.key pentru a-l păstra. Confirmați că CSR-ul conține ceea ce vă așteptați înainte de a-l trimite, fie cu decodificatorul nostru de CSR, fie local:

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

Verificați dacă intrările SAN sunt listate și dacă semnătura este verificată. Dacă preferați să nu utilizați deloc linia de comandă, generatorul nostru de CSR produce aceeași pereche direct în browser. Mai multe informații despre comenzile care stau la bază găsiți în ghidul nostru despre comenzile OpenSSL.

Obțineți emiterea certificatului

Trimiteți CSR-ul către CA, alegeți tipul de certificat care corespunde cu ceea ce protejați și finalizați validarea. Un certificat pentru un singur domeniu acoperă un singur nume de gazdă, un certificat wildcard acoperă fiecare subdomeniu de prim nivel, iar un certificat multi-domeniu (SAN) acoperă o listă de nume fără legătură între ele. În spatele unui balansor de sarcină, multi-domeniu este alegerea obișnuită, întrucât o instanță HAProxy servește de obicei mai multe site-uri.

CA-ul returnează o arhivă care conține certificatul dvs. și lanțul intermediar, de obicei ca un fișier pachet CA. Ambele sunt deja în format PEM, care este exact ce vă trebuie. Planificați reînnoirea acum, nu mai târziu: începând cu 15 martie 2026, un certificat TLS de încredere publică poate fi valabil pentru cel mult 200 de zile, scăzând la 100 de zile în martie 2027 și la 47 de zile în martie 2029, astfel încât înlocuirea manuală va înceta destul de curând să mai fie practică.

Construiți fișierul PEM pe care îl va citi HAProxy

Creați un director pentru certificate și asamblați fișierul acolo. Păstrați totul într-un singur loc de la început; împărțirea acestuia între directorul home, /etc/haproxy și /etc/ssl este modul în care oamenii ajung să editeze un fișier în timp ce HAProxy citește altul.

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

Concatenați certificatul, apoi intermediarii, apoi cheia privată. Redirecționarea trebuie să ruleze ca root, așa că trimiteți-o printr-un pipe către tee în loc să scrieți sudo cat ... > /etc/haproxy/certs/..., lucru care eșuează cu o eroare de permisiune, întrucât shell-ul deschide fișierul de ieșire ca utilizatorul dvs. propriu înainte ca sudo să ruleze vreodată:

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

Acest fișier conține acum cheia privată în text simplu, așa că protejați-l înainte de a merge mai departe:

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

Permisiunile exclusiv pentru root sunt corecte aici, nu un obstacol. HAProxy este pornit cu privilegii de superutilizator, ceea ce manualul său precizează că este necesar pentru a putea comuta ulterior la propriul utilizator neprivilegiat, iar el citește certificatul în timpul acestei porniri. Nu este nevoie să extindeți permisiunile astfel încât utilizatorul haproxy să poată citi cheia și nu ar trebui să o faceți.

Dacă ați construit CSR-ul pe o altă mașină, copiați fișierele mai întâi și ștergeți copiile din directorul de tranzit ulterior:

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

Configurați HAProxy

Deschideți /etc/haproxy/haproxy.cfg într-un editor de terminal direct pe server, precum nano sau vim. Editați-l pe loc, nu pe o stație de lucru, astfel încât să nu reîncărcați niciodată un fișier diferit de cel testat.

Frontend-ul

Un frontend poate accepta atât HTTP simplu, cât și HTTPS. Legați (bind) portul 80 pentru redirecționare, legați portul 443 cu certificatul și trimiteți orice altceva către 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 oferă HTTP/2 și revine la HTTP/1.1. Redirecționarea se declanșează doar atunci când cererea nu a ajuns prin TLS, lucru pe care ssl_fc îl testează, astfel încât cererile pe portul 443 trec direct.

Puneți toate opțiunile TLS pe acea singură linie bind

Aici configurațiile HAProxy dau greș cel mai des, și eșuează în tăcere. Ghidurile prezintă frecvent întărirea (hardening) TLS ca un al doilea pas, arătând o linie bind nouă pentru portul 443 cu opțiuni suplimentare pe ea. Dacă adăugați acea linie în loc să o editați pe cea existentă, ajungeți cu două linii bind pentru același port, iar HAProxy nu se plânge. Pornește și deschide două socket-uri de ascultare separate pe portul 443, cu setări TLS diferite. Pe care socket ajunge o anumită conexiune nu este ceva ce controlați, așa că întărirea dvs. acoperă aproximativ jumătate din trafic.

Nici verificarea configurației nu detectează acest lucru, iar propria sa documentație explică de ce: -c „efectuează doar o verificare a fișierelor de configurare și iese înainte de a încerca legarea (bind)„. Un listener duplicat este o condiție care apare în momentul legării, așa că o verificare de sintaxă nu o va vedea niciodată.

Setați valori implicite globale în schimb, astfel încât fiecare linie bind din fișier să le moștenească, și nu mai există nimic de duplicat:

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

Merită să știți înainte de a copia acest bloc oriunde: ssl-min-ver este deja implicit setat la TLSv1.2, în cuvintele proprii ale HAProxy. Setarea sa la TLSv1.2 nu schimbă nimic și doar documentează intenția, ceea ce este în regulă, dar nu este îmbunătățirea de securitate care este adesea prezentată. Cele două setări de cifruri fac muncă reală și sunt separate intenționat: ssl-default-bind-ciphers se aplică pentru TLS 1.2 și versiunile inferioare, ssl-default-bind-ciphersuites se aplică pentru TLS 1.3. Setați doar prima, iar suitele dvs. TLS 1.3 rămân la valorile implicite.

Backend-ul

Dați fiecărui server o adresă reală. Acest lucru contează mai mult decât pare:

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

O linie server scrisă ca server web1 :80 check, fără adresă specificată, nu generează nicio eroare. HAProxy o acceptă și rezolvă adresa lipsă la 0.0.0.0, pe care manualul său o tratează ca o valoare specială, însemnând că conexiunea este redirecționată către aceeași adresă IP la care s-a conectat clientul. Acea adresă este HAProxy însuși, deci backend-ul indică în tăcere către portul 80 propriu al HAProxy, care este chiar frontend-ul pe care tocmai l-ați configurat. Traficul se întoarce în buclă în redirecționare, în loc să ajungă la vreo aplicație, iar verificările de sănătate par sănătoase, pentru că ceva chiar ascultă acolo. Dacă un balansor de sarcină răspunde la fiecare cerere HTTPS cu o redirecționare către el însuși, verificați mai întâi liniile server.

Deoarece HAProxy termină TLS-ul, backend-urile primesc HTTP simplu pe portul 80 și nu au nevoie de propriul certificat. Dacă politica dvs. impune criptarea și pe acest segment, adăugați ssl verify required și un fișier CA la liniile server și indicați-le către portul 443 în schimb.

Transmiteți schema originală către backend. Deoarece backend-ul primește acum HTTP simplu, o aplicație care generează URL-uri absolute, așa cum fac WordPress, Django și Rails, le va genera cu http://, ceea ce apare ca și conținut mixt sau ca o buclă de redirecționare pe care aplicația însăși o creează. Adăugați o linie la frontend:

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

și una la backend, care de asemenea transmite adresa IP reală a clientului:

option forwardfor

Majoritatea framework-urilor trebuie apoi instruite să aibă încredere în acele antete; acea parte este configurată în aplicație, nu în HAProxy.

Verificați configurația înainte de a o aplica

Nu reporniți niciodată un balansor de sarcină pe un fișier neverificat. Validați mai întâi:

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

Cu -V afișează Configuration file is valid la succes și returnează codul de ieșire zero. Fără el, succesul este tăcut. Orice avertisment este raportat indiferent dacă fișierul este valid sau nu, așa că citiți rezultatul în loc să vă bazați pe absența textului roșu.

Reîncărcați în loc să reporniți

sudo systemctl reload haproxy

Distincția este reală pe un balansor de sarcină. O reîncărcare pornește un proces nou și semnalează celui vechi să „termine ce fac și să plece”, astfel încât cererile deja aflate în desfășurare se finalizează normal. O repornire semnalează procesului vechi să „se termine imediat, fără a finaliza ce făcea”, ceea ce întrerupe conexiunile active, inclusiv încărcările și apelurile API de lungă durată. Folosiți repornirea doar atunci când o reîncărcare nu poate prelua modificarea, cum ar fi după alterarea setărilor de proces din secțiunea globală.

Confirmați că serviciul a revenit și ascultă pe ambele porturi:

sudo systemctl status haproxy
sudo ss -tlnp | grep haproxy

Exact un socket de ascultare per port este ceea ce doriți aici. Două pe portul 443 înseamnă că aveți linia bind duplicată descrisă mai sus.

Verificați dacă certificatul este servit

Verificați ce prezintă efectiv HAProxy, inclusiv lanțul, direct de pe server:

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

Citiți secțiunea Certificate chain din partea de sus a rezultatului. Certificatul dvs. ar trebui să apară la profunzimea 0 și intermediarul la profunzimea 1. Dacă profunzimea 1 lipsește, intermediarul nu a ajuns niciodată în fișierul PEM, iar site-ul va funcționa în unele browsere, dar va eșua în altele. Ignorați linia Verify return code atunci când evaluați acest lucru: ea raportează doar verdictul lanțului și poate apărea ca reușit în situații care nu au nicio legătură cu ceea ce testați.

Apoi confirmați din exterior, unde rezultatul reflectă ceea ce primesc vizitatorii reali. SSL Checker-ul nostru raportează certificatul, lanțul și data de expirare.

Reînnoiri și automatizare

Înlocuirea fișierului PEM reprezintă întreaga procedură de reînnoire: reconstruiți-l din noul certificat și aceeași cheie sau una nouă, apoi reîncărcați. Nimic din configurația HAProxy nu face referire la data de expirare, deci nu este nevoie de nicio editare de configurare atât timp cât calea fișierului rămâne aceeași.

Cu duratele de viață ale certificatelor scurtându-se, automatizarea merită configurată acum. HAProxy a primit un client ACME integrat în versiunea 3.2, configurat printr-o secțiune acme. Tratați-l ca pe o previzualizare, nu ca infrastructură de producție deocamdată: este încă marcat experimental în 3.4 și necesită expose-experimental-directives în secțiunea globală, suportă doar tipurile de provocare http-01, dns-01 și dns-persist-01, iar certificatele pe care le generează trebuie extrase din socket-ul de statistici pentru a ajunge pe disc. Tipul dns-persist-01, adăugat în 3.4, folosește o înregistrare TXT statică setată o singură dată și care nu se schimbă niciodată între reînnoiri, deci nu necesită acces de scriere la API-ul furnizorului DNS la fiecare reînnoire. Alternativa consacrată este să rulați un client ACME extern și să faceți ca pasul său de implementare să reconstruiască fișierul PEM și să reîncarce HAProxy, ceea ce este același model descris în ghidul nostru ACME pentru Apache și NGINX.

Întrebări frecvente

Dacă certificatul este instalat, dar browserele încă se plâng, ghidurile noastre despre erorile SSL comune acoperă cauzele obișnuite, cel mai adesea un lanț incomplet sau un nume pe care certificatul nu îl listează.