Come installare HAproxy su Debian 12

HAProxy su Debian 12: installazione e primo setup

HAProxy è un load balancer e reverse proxy molto usato in ambienti Linux per distribuire traffico HTTP/HTTPS, fare health check sui backend e aggiungere un punto di ingresso stabile davanti ad applicazioni, cluster e servizi web. Su Debian 12 l’installazione è lineare, ma vale la pena partire subito con una configurazione minima corretta, verificando stato del servizio, sintassi e log prima di esporre il proxy in produzione.

In questa guida trovi una procedura essenziale ma completa: installazione del pacchetto, verifica del demone, configurazione base con frontend e backend, test di funzionamento e controlli finali. L’obiettivo è arrivare a un HAProxy operativo, con una configurazione semplice da estendere.

Prerequisiti e contesto operativo

Assumo Debian 12 aggiornato, accesso root o sudo, e almeno un backend HTTP già attivo da raggiungere sulla rete. Se stai mettendo HAProxy davanti a più server, verifica prima connettività, DNS interno e porte aperte. Se invece vuoi usarlo solo come reverse proxy locale, basta che il servizio applicativo risponda su localhost o su un IP raggiungibile dal server HAProxy.

Prima di toccare la configurazione, conviene sapere cosa devi ottenere:

• un servizio HAProxy installato e avviato come unità systemd;
• una configurazione valida in /etc/haproxy/haproxy.cfg;
• un frontend in ascolto su una porta definita, tipicamente 80 o 443;
• almeno un backend raggiungibile per i test;
• una verifica finale con haproxy -c e test HTTP con curl.

Se il tuo obiettivo è alta affidabilità, il passo successivo sarà aggiungere più backend, health check più precisi, logging strutturato e, se serve, TLS termination. Qui partiamo dalla base solida.

Installazione del pacchetto

Su Debian 12 HAProxy è disponibile nei repository ufficiali. L’installazione standard è questa:

sudo apt update
sudo apt install haproxy

Dopo l’installazione, controlla che il pacchetto sia presente e che il servizio sia stato registrato correttamente da systemd:

haproxy -v
systemctl status haproxy --no-pager

Atteso:

• haproxy -v mostra la versione installata;
• systemctl status indica active (running) oppure almeno inactive ma senza errori di configurazione, se il servizio non è ancora partito;
• se il servizio è in errore, il problema è quasi sempre nella configurazione iniziale o in una porta già occupata.

Se il demone non parte subito, non forzare ancora modifiche profonde: prima verifica la sintassi del file di configurazione e i log del servizio.

Struttura dei file su Debian 12

I file principali sono pochi:

• /etc/haproxy/haproxy.cfg: configurazione principale;
• /etc/default/haproxy: opzioni di avvio del servizio, se necessarie;
• /var/log: log, se hai configurato rsyslog o journald in modo appropriato;
• /run/haproxy o directory simili: socket o file runtime, se usati.

Su Debian, il comportamento del logging dipende dalla configurazione. Se vuoi vedere subito i messaggi, puoi iniziare a leggere il journal:

journalctl -u haproxy -n 50 --no-pager

Se il servizio segnala errori di bind, sintassi o permessi, li trovi lì. È il primo punto da controllare quando qualcosa non torna.

Configurazione minima funzionante

Prima di fare routing complesso, conviene partire da una configurazione base che esponga una porta e inoltri verso un backend unico. Fai un backup del file esistente prima di modificarlo:

sudo cp /etc/haproxy/haproxy.cfg /etc/haproxy/haproxy.cfg.bak.$(date +%F-%H%M%S)

Un esempio minimo di configurazione HTTP è questo:

global
    log /dev/log local0
    log /dev/log local1 notice
    chroot /var/lib/haproxy
    stats socket /run/haproxy/admin.sock mode 660 level admin expose-fd listeners
    stats timeout 30s
    user haproxy
    group haproxy
    daemon


defaults
    log     global
    mode    http
    option  httplog
    option  dontlognull
    timeout connect 5s
    timeout client  50s
    timeout server  50s

frontend fe_http
    bind *:80
    default_backend be_app

backend be_app
    balance roundrobin
    server app1 127.0.0.1:8080 check

Questa configurazione fa tre cose essenziali:

• definisce parametri globali e di default;
• ascolta su porta 80;
• inoltra il traffico al backend 127.0.0.1:8080.

Se il tuo backend non è locale, sostituisci l’indirizzo IP con quello del server applicativo. Se vuoi usare più nodi, aggiungi più righe server nel blocco backend.

Verifica della sintassi prima del riavvio

Questo è il controllo più importante prima di ricaricare il servizio. HAProxy ha un validatore integrato:

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

Atteso:

• Configuration file is valid;
• nessun errore di parsing;
• nessun errore su bind, permessi, o direttive sconosciute.

Se compare un errore, correggi prima di andare oltre. Gli errori tipici sono:

• porta già occupata da un altro servizio;
• indentazione o direttiva errata;
• backend non raggiungibile se hai usato controlli o opzioni più avanzate;
• mancanza di permessi su socket o file di runtime.

Quando la configurazione è valida, puoi avviare o riavviare il servizio:

sudo systemctl enable --now haproxy

Se il servizio era già attivo e hai modificato la configurazione, usa un reload controllato:

sudo systemctl reload haproxy

Su un cambio semplice, il reload è preferibile al restart perché riduce l’interruzione del traffico. Se il reload fallisce, systemd di solito mostra il motivo nei log.

Test del frontend e del backend

Una volta partito il servizio, verifica che la porta sia in ascolto:

sudo ss -lntp | grep ':80'

Atteso:

• una riga che mostra haproxy in ascolto su :80;
• nessun conflitto con Apache, Nginx o altri demoni che occupano la stessa porta.

Poi testa la risposta HTTP dal server stesso:

curl -I http://127.0.0.1/

Se il backend risponde con una pagina o un HTTP/1.1 200, il flusso base è corretto. Se ottieni un 503 o un timeout, il problema è quasi sempre nel backend, nella porta sbagliata o nella rete tra HAProxy e applicazione.

Per capire se il proxy sta effettivamente inoltrando, puoi fare una richiesta più esplicita e controllare i log del backend applicativo. Se il backend è un web server locale, verifica anche lì:

sudo journalctl -u apache2 -n 20 --no-pager
sudo journalctl -u nginx -n 20 --no-pager

In alternativa, se il servizio applicativo ha log file dedicati, controlla il path specifico della tua installazione. Il punto è sempre lo stesso: capire se la richiesta arriva a HAProxy e da lì viene passata al backend.

Bilanciamento con più backend

Quando hai più server applicativi, puoi aggiungerli nello stesso backend. Esempio:

backend be_app
    balance roundrobin
    option httpchk GET /health
    server app1 10.0.0.11:8080 check
    server app2 10.0.0.12:8080 check
    server app3 10.0.0.13:8080 check

Qui hai tre elementi utili:

• balance roundrobin distribuisce le richieste in modo uniforme;
• check abilita il controllo di salute del nodo;
• option httpchk fa un controllo HTTP su un endpoint dedicato, ad esempio /health.

Questo tipo di health check è molto più utile di un semplice test di porta, perché ti dice se l’applicazione è davvero pronta a servire traffico. Se l’endpoint /health restituisce un codice diverso da quello atteso, HAProxy può escludere il nodo malato.

Se la tua applicazione non ha un endpoint di salute, creane uno. È una piccola modifica che migliora molto la gestione operativa.

Accesso allo stato e diagnostica

Una delle funzioni più utili di HAProxy è il socket di amministrazione. Nella configurazione base sopra è già presente:

stats socket /run/haproxy/admin.sock mode 660 level admin expose-fd listeners

Con questo socket puoi interrogare lo stato del proxy e dei backend. Ad esempio:

echo "show info" | sudo socat stdio /run/haproxy/admin.sock
echo "show stat" | sudo socat stdio /run/haproxy/admin.sock

Atteso:

• show info restituisce informazioni di runtime;
• show stat mostra frontend, backend e server con stato, code, sessioni e health.

Se non hai socat, puoi installarlo oppure usare strumenti equivalenti. Questo socket è molto utile in troubleshooting, perché ti evita di andare a tentoni: vedi subito se un backend è UP, DOWN o in errore.

Logging utile per produzione

In ambiente reale il logging non è opzionale. Senza log leggibili, ogni incidente si allunga. La configurazione minima già manda i log verso syslog. Devi però assicurarti che il tuo sistema li riceva e li conservi nel posto giusto.

Se usi journald, puoi leggere così:

journalctl -u haproxy -f

Se vuoi un file dedicato con rsyslog, la configurazione dipende dal tuo setup, ma l’obiettivo è avere almeno:

• timestamp;
• frontend e backend coinvolti;
• status code;
• tempi di risposta;
• eventuali errori di connessione al backend.

Per operare bene, i log devono aiutarti a distinguere tra problema di frontend, problema del backend o latenza anomala. Se vedi molti 5xx, il primo controllo è sempre il backend e la sua raggiungibilità.

Avvio automatico e gestione del servizio

Su Debian 12 è buona pratica abilitare il servizio all’avvio solo quando la configurazione è valida e testata:

sudo systemctl enable haproxy

Per controllare lo stato operativo:

systemctl is-enabled haproxy
systemctl is-active haproxy

Se devi fare una modifica, segui sempre questo ordine:

1. salva backup del file di configurazione;
2. modifica il file;
3. valida con haproxy -c;
4. applica con reload;
5. verifica con curl, ss e log.

Questo riduce il rischio di downtime causato da un errore di sintassi o da un backend sbagliato.

Esempio di configurazione un po’ più completa

Se vuoi una base più realistica, puoi usare una configurazione con redirect da HTTP a HTTPS, oppure una sezione stats. Qui sotto un esempio con pagina di stato minimale e frontend HTTP:

global
    log /dev/log local0
    log /dev/log local1 notice
    chroot /var/lib/haproxy
    stats socket /run/haproxy/admin.sock mode 660 level admin expose-fd listeners
    stats timeout 30s
    user haproxy
    group haproxy
    daemon

defaults
    log global
    mode http
    option httplog
    option dontlognull
    timeout connect 5s
    timeout client 50s
    timeout server 50s

frontend fe_http
    bind *:80
    acl is_stats path /stats
    use_backend be_stats if is_stats
    default_backend be_app

backend be_app
    balance roundrobin
    option httpchk GET /health
    server app1 127.0.0.1:8080 check

backend be_stats
    stats enable
    stats uri /stats
    stats refresh 10s

Con questa variante puoi aprire http://IP_DEL_SERVER/stats e vedere una dashboard base. Se la usi in produzione, proteggi l’accesso con ACL, autenticazione o restrizioni IP. Esporre la pagina stats senza controllo non è una buona idea.

Errori frequenti e come riconoscerli

I problemi più comuni in fase di installazione sono prevedibili:

• porta occupata: ss -lntp mostra un altro processo su :80;
• backend sbagliato: curl verso l’IP e la porta del backend fallisce già senza HAProxy;
• config non valida: haproxy -c segnala errore di sintassi o direttiva;
• permessi socket: il file in /run/haproxy non è leggibile dal gruppo corretto;
• health check fallito: il backend risponde ma non all’endpoint previsto.

La regola pratica è semplice: prima verifica il backend direttamente, poi verifica HAProxy, poi i log. Invertire l’ordine fa perdere tempo.

Hardening minimo da fare subito

Anche in un setup piccolo ci sono alcune cose da sistemare appena finita l’installazione:

• non lasciare aperta la pagina stats senza controllo;
• usa health check reali, non solo test di porta;
• limita l’accesso al socket di amministrazione;
• mantieni aggiornato il pacchetto con i normali update di sistema;
• se HAProxy espone servizi pubblici, valuta TLS termination e policy di sicurezza coerenti.

Se il server è esposto su Internet, considera anche firewall e restrizioni a livello di rete. HAProxy è un componente di frontiera: merita la stessa attenzione di un web server pubblico.

Quando passare alla configurazione TLS

Se il tuo uso finale prevede HTTPS, la parte di installazione resta identica, ma cambiano le sezioni bind e la gestione dei certificati. In quel caso dovrai preparare un file PEM corretto, configurare il bind su :443 e decidere se terminare TLS su HAProxy o fare passthrough verso i backend.

La scelta dipende dall’architettura:

• TLS termination su HAProxy: utile se vuoi centralizzare certificati, ACL e routing L7;
• passthrough: utile se vuoi lasciare TLS ai backend o preservare end-to-end encryption senza ispezione HTTP;
• bridge parziale: possibile ma va progettato bene, non improvvisato.

Se ti serve solo mettere in piedi il servizio, parti con HTTP interno e poi introduci TLS con una modifica separata e testata.

Sequenza consigliata in pratica

Se vuoi la versione operativa sintetica, l’ordine giusto è questo:

1. aggiorna i pacchetti;
2. installa haproxy;
3. salva il backup di /etc/haproxy/haproxy.cfg;
4. scrivi una configurazione minima con un frontend e un backend;
5. valida con haproxy -c -f /etc/haproxy/haproxy.cfg;
6. avvia o ricarica il servizio con systemd;
7. testa con ss, curl e journalctl;
8. aggiungi health check, logging e stato solo dopo che la base funziona.

Questa sequenza evita il classico errore di mettere mano a troppe cose insieme. Con HAProxy, come con molti componenti di rete, la configurazione minima che funziona è il miglior punto di partenza.

Assunzione: il server Debian 12 ha accesso al backend applicativo sulla rete e non esistono vincoli particolari di firewall, SELinux o policy di sicurezza che richiedano una procedura diversa.

Verifiche finali e rollback

Prima di considerare chiusa l’installazione, controlla questi punti:

• systemctl status haproxy mostra active (running);
• haproxy -c -f /etc/haproxy/haproxy.cfg restituisce configurazione valida;
• ss -lntp | grep ':80' mostra HAProxy in ascolto;
• curl -I http://127.0.0.1/ risponde con l’output atteso;
• journalctl -u haproxy -n 50 non mostra errori ricorrenti.

Se qualcosa va storto dopo una modifica, il rollback minimo è ripristinare il backup della configurazione e ricaricare il servizio:

sudo cp /etc/haproxy/haproxy.cfg.bak.YYYY-MM-DD-HHMMSS /etc/haproxy/haproxy.cfg
sudo haproxy -c -f /etc/haproxy/haproxy.cfg
sudo systemctl reload haproxy

Se il problema è più grave e il servizio non deve restare esposto, puoi fermarlo temporaneamente con systemctl stop haproxy mentre correggi la configurazione. Questo ha impatto sul traffico, quindi usalo solo se sai che il frontend alternativo o il downtime sono accettabili.

Con questi passaggi hai un’installazione pulita e verificata di HAProxy su Debian 12, pronta per crescere verso scenari più avanzati come bilanciamento multi-backend, TLS termination, ACL, stick table e osservabilità più completa.