Nginx come web server, reverse proxy L7/L4 e terminazione TLS

Introduzione

Per comprendere davvero Nginx è utile vederlo all’opera in scenari completi:

come web server statico
come reverse proxy layer 7 con più backend Node.js
come proxy / load balancer layer 4
come terminatore TLS che espone un sito pubblico con TLS 1.3 e HTTP/2

Questo articolo segue idealmente gli esempi in cui vengono creati i container nodeapp in Docker. Per i dettagli sulla creazione dell’immagine Node e dei container si può fare riferimento agli articoli precedenti dedicati a Docker; qui l’attenzione è sulla configurazione di Nginx.

Obiettivo finale:

partire da un’installazione Nginx “pulita”
costruire passo passo una configurazione leggibile
capire come si passa da localhost a un dominio pubblico con certificato Let’s Encrypt

Installazione di Nginx (macOS con Homebrew)

Su macOS è comodo installare Nginx tramite Homebrew:

brew install nginx

L’installazione crea:

il binario nginx
una configurazione predefinita (tipicamente in /usr/local/etc/nginx/nginx.conf o similare)
un server in ascolto su una porta di default (spesso 8080 o 8081)

Per studiare Nginx conviene non affidarsi alla configurazione di default, ma scriverne una minimale da zero. Prima si può fare un backup del file esistente e poi sovrascriverlo.

Configurazione minima: web server statico

Una configurazione Nginx layer 7 minima richiede:

il blocco events (anche vuoto, ma obbligatorio)
il blocco http (contesto layer 7)
almeno un blocco server con una direttiva listen

Esempio di nginx.conf minimale:

1
events {
2
    worker_connections 1024;
3
}
4

5
http {
6
    server {
7
        listen 8080;
8
    }
9
}

Con questa configurazione Nginx è in ascolto sulla porta 8080, ma non sa ancora da dove servire contenuti statici.

Servire file statici con `root`

Per servire contenuti statici (HTML, CSS, JavaScript, immagini) occorre indicare una directory radice tramite la direttiva root all’interno del blocco server (o di un blocco location).

Supponiamo di avere:

/Users/<utente>/Documents/nginx-course/
  index.html

Allora si può scrivere:

1
http {
2
    server {
3
        listen 8080;
4
        root /Users/<utente>/Documents/nginx-course;
5
    }
6
}

Visitando http://localhost:8080/ Nginx, non trovando altre regole, servirà il file index.html nella directory indicata.

Più “siti” con blocchi `location`

All’interno di un server si possono definire percorsi diversi con blocchi location.

Esempio di struttura:

/Users/<utente>/Documents/nginx-course/
  site1/index.html
  site2/index.html

Configurazione:

1
http {
2
    server {
3
        listen 8080;
4

5
        # Root generale del server
6
        root /Users/<utente>/Documents/nginx-course;
7

8
        # / → index.html nella root
9
        location / {
10
            # usa la root di server
11
        }
12

13
        # /site1 → /Users/.../site1/index.html
14
        location /site1 {
15
            # root resta quella del server
16
        }
17

18
        # /site2 → /Users/.../site2/index.html
19
        location /site2 {
20
            # root resta quella del server
21
        }
22
    }
23
}

Con questa configurazione:

http://localhost:8080/ → index.html nella root
http://localhost:8080/site1 → site1/index.html
http://localhost:8080/site2 → site2/index.html

Statico da directory esterna con `location` dedicato

A volte le risorse (es. immagini) risiedono in una directory fuori dalla root principale.

Esempio:

/Users/<utente>/Pictures/nginx-images/
  postgres.png

Si può creare un location dedicato:

1
http {
2
    server {
3
        listen 8080;
4
        root /Users/<utente>/Documents/nginx-course;
5

6
        location / {
7
            # root principale
8
        }
9

10
        location /images {
11
            root /Users/<utente>/Pictures/nginx-images;
12
        }
13
    }
14
}

Richieste a:

/images/postgres.png → /Users/<utente>/Pictures/nginx-images/postgres.png

Attenzione: il percorso effettivo è dato da root + parte di path dopo il prefisso location.

Regex e `return` per bloccare estensioni

Con location è possibile usare espressioni regolari per intercettare pattern specifici, ad esempio per bloccare il download di tutti i file .jpg o .jpeg.

Esempio:

1
http {
2
    server {
3
        listen 8080;
4
        root /Users/<utente>/Documents/nginx-course;
5

6
        # Tutte le richieste che terminano con .jpg o .jpeg
7
        location ~ \.(jpe?g)$ {
8
            return 403;
9
        }
10
    }
11
}

In questo modo:

GET /foto.jpg → 403 Forbidden
GET /foto.png → servito normalmente (se esiste)

Le regex nei blocchi location permettono controlli sofisticati sui path senza modificare il codice dell’applicazione.

Reverse proxy layer 7 con più backend Node.js

Per usare Nginx come reverse proxy layer 7 verso più backend Node.js si usano:

il contesto http
il blocco upstream per definire il gruppo di server
uno o più blocchi server con proxy_pass

Scenario di esempio

Si considerano quattro applicazioni Node.js esposte sull’host (ad esempio tramite Docker) con le seguenti porte:

localhost:2222
localhost:3333
localhost:4444
localhost:5555

Ogni app espone:

/ → homepage che identifica l’istanza (es. “I am app 2222”)
/app1 → sezione app1
/app2 → sezione app2
/admin → area amministrativa

`upstream` e round-robin

Per bilanciare il traffico in round-robin tra tutti i backend:

1
http {
2
    upstream all_backend {
3
        server 127.0.0.1:2222;
4
        server 127.0.0.1:3333;
5
        server 127.0.0.1:4444;
6
        server 127.0.0.1:5555;
7
    }
8

9
    server {
10
        listen 80;
11

12
        location / {
13
            proxy_pass http://all_backend;
14
        }
15
    }
16
}

Ogni richiesta a http://localhost/ viene inoltrata a uno dei server in all_backend secondo round-robin (1 → 2 → 3 → 4 → di nuovo 1 → ...).

`ip_hash` e sticky session

Se si usa l’algoritmo ip_hash, Nginx applica un hashing sull’IP del client per scegliere sempre lo stesso backend per quel client.

1
upstream all_backend {
2
    ip_hash;
3
    server 127.0.0.1:2222;
4
    server 127.0.0.1:3333;
5
    server 127.0.0.1:4444;
6
    server 127.0.0.1:5555;
7
}

In questo caso ogni client viene “stickato” a un server. Questo approccio è talvolta usato per applicazioni stateful in memoria, anche se l’architettura moderna tende a privilegiare servizi stateless.

Due upstream distinti per `/app1` e `/app2`

È possibile dividere le app in gruppi diversi e instradare in base al path:

1
http {
2
    upstream app1_backend {
3
        server 127.0.0.1:2222;
4
        server 127.0.0.1:3333;
5
    }
6

7
    upstream app2_backend {
8
        server 127.0.0.1:4444;
9
        server 127.0.0.1:5555;
10
    }
11

12
    server {
13
        listen 80;
14

15
        location / {
16
            proxy_pass http://all_backend;
17
        }
18

19
        location /app1 {
20
            proxy_pass http://app1_backend;
21
        }
22

23
        location /app2 {
24
            proxy_pass http://app2_backend;
25
        }
26
    }
27
}

In questo modo:

/ continua a bilanciare su tutti i backend
/app1 bilancia solo tra 2222 e 3333
/app2 bilancia solo tra 4444 e 5555

Proteggere `/admin` dal traffico pubblico

Per evitare che la sezione admin sia raggiungibile dalla porta pubblica (es. 80) ma resti accessibile solo tramite le porte interne (2222, 3333, …), si può bloccare il path a livello di Nginx:

1
server {
2
    listen 80;
3

4
    location / {
5
        proxy_pass http://all_backend;
6
    }
7

8
    location /admin {
9
        return 403;
10
    }
11
}

In questo scenario:

http://localhost/admin → 403 Forbidden
http://localhost:2222/admin (o porte interne) → ancora accessibile, ad esempio solo dalla rete interna

Nginx come proxy / load balancer layer 4 (`stream`)

Finora Nginx ha lavorato in layer 7 (contesto http), leggendo le richieste HTTP e instradando in base al path. In alcuni casi serve invece un proxy layer 4 (TCP puro), che non interpreta HTTP ma si limita a inoltrare connessioni.

Per questo Nginx offre il contesto stream.

Differenza concettuale

In layer 7 (HTTP):
- Nginx termina le connessioni TCP dal client
- apre a sua volta connessioni verso i backend
- legge e interpreta la richiesta HTTP (es. path, header)
- può decidere il backend in base alla URI
In layer 4 (stream):
- Nginx non interpreta il protocollo applicativo
- riceve una connessione TCP dal client
- ne apre una verso un backend
- inoltra byte da una parte all’altra (TCP forwarding)

Il vantaggio del layer 4 è che qualsiasi protocollo sopra TCP (HTTP, WebSocket, SMTP, protocolli custom) viene trattato allo stesso modo.

Esempio di configurazione `stream`

Configurazione come proxy TCP con bilanciamento round-robin tra i quattro backend:

1
stream {
2
    upstream all_backend {
3
        server 127.0.0.1:2222;
4
        server 127.0.0.1:3333;
5
        server 127.0.0.1:4444;
6
        server 127.0.0.1:5555;
7
    }
8

9
    server {
10
        listen 80;
11
        proxy_pass all_backend;
12
    }
13
}

Nel contesto stream:

non esistono location
non si può usare proxy_pass http://... con path
la scelta del backend avviene per connessione, non per singola richiesta HTTP

Se un browser mantiene la stessa connessione TCP (tipico con HTTP/1.1 e keep-alive), tutte le richieste successive viaggeranno verso lo stesso backend finché la connessione rimane aperta.

Questo si vede bene usando strumenti come telnet o nc: ogni nuova connessione TCP viene inoltrata in round-robin a un backend diverso.

Esporre Nginx su Internet e DNS

Per rendere il server accessibile da Internet in modo controllato occorrono:

un router o firewall che faccia port forwarding
un dominio o hostname DNS che punti all’IP pubblico

Port forwarding su router

Configurazione tipica:

inoltrare la porta 80 pubblica verso la porta 80 della macchina che esegue Nginx
inoltrare la porta 443 pubblica verso la porta 443 della stessa macchina

In questo modo:

http://<IP_pubblico> → arriva a Nginx (porta 80)
https://<IP_pubblico> → arriva a Nginx (porta 443)

Questa operazione espone il server su Internet ed è delicata: è essenziale assicurarsi che Nginx sia configurato in modo sicuro.

Hostname DNS

Per evitare di usare direttamente l’IP pubblico si può registrare un hostname tramite un servizio DNS (anche dinamico), ad esempio:

nginx-test.dns.net → punta all’IP pubblico della connessione

Una volta propagato il record DNS, http://nginx-test.dns.net/ raggiunge lo stesso server raggiungibile tramite IP pubblico.

TLS con Let’s Encrypt e certbot

Per abilitare HTTPS con un certificato valido si può usare Let’s Encrypt tramite certbot.

Flusso semplificato

Installare certbot (ad esempio via Homebrew su macOS).
Arrestare temporaneamente Nginx se si usa la modalità standalone.
Eseguire certbot indicando il dominio (es. nginx-test.dns.net).
Certbot contatta Let’s Encrypt, verifica il controllo sul dominio e genera:
- il certificate chain (pubblico)
- la private key
I file vengono salvati tipicamente in /etc/letsencrypt/live/<dominio>/.
Nginx viene riconfigurato per usare questi file nelle direttive SSL.

Configurazione SSL in Nginx

Esempio semplificato di server HTTPS:

1
http {
2
    server {
3
        listen 443 ssl http2;
4
        server_name nginx-test.dns.net;
5

6
        ssl_certificate     /etc/letsencrypt/live/nginx-test.dns.net/fullchain.pem;
7
        ssl_certificate_key /etc/letsencrypt/live/nginx-test.dns.net/privkey.pem;
8

9
        location / {
10
            proxy_pass http://all_backend;
11
        }
12
    }
13
}

Punti chiave:

listen 443 ssl http2:
- 443: porta standard HTTPS
- ssl: attiva il TLS
- http2: abilita il protocollo HTTP/2
ssl_certificate: catena di certificati (incluso il certificato del sito)
ssl_certificate_key: chiave privata corrispondente

Se la configurazione è corretta, visitando https://nginx-test.dns.net/ il browser mostrerà una connessione sicura con certificato valido emesso da Let’s Encrypt.

Abilitare esplicitamente TLS 1.3 e HTTP/2

Di default molte installazioni Nginx abilitano TLS 1.2 e, a seconda della versione, possono non attivare TLS 1.3.

Per forzare l’uso di TLS 1.3 si può aggiungere:

1
server {
2
    listen 443 ssl http2;
3

4
    ssl_protocols TLSv1.3;
5
    # ssl_ciphers può essere personalizzato per forzare solo suite moderne
6
}

Con ssl_protocols TLSv1.3;:

i client che supportano solo TLS 1.2 non riusciranno a connettersi
la connessione utilizzerà sempre TLS 1.3, con:
- handshake più rapido (meno round-trip)
- ciphersuite moderne (es. basate su Diffie-Hellman effimero)

Per HTTP/2 è sufficiente mantenere http2 nel listen:

1
listen 443 ssl http2;

I browser moderni negozieranno automaticamente HTTP/2 tramite ALPN quando possibile.

Riepilogo

In questo articolo Nginx è stato visto in più ruoli:

Web server statico: root, location, regex e codici di ritorno
Reverse proxy layer 7: upstream, proxy_pass, round-robin, ip_hash, path-based routing e blocco selettivo di /admin
Proxy / load balancer layer 4: contesto stream e forwarding TCP trasparente
Terminazione TLS: integrazione con Let’s Encrypt, configurazione di certificato e chiave, abilitazione di TLS 1.3 e HTTP/2

Capire questi aspetti permette di leggere e progettare configurazioni Nginx con maggiore consapevolezza, scegliendo di volta in volta:

se lavorare a livello di HTTP (layer 7) o TCP (layer 4)
come distribuire il traffico tra più backend
come esporre in sicurezza il servizio verso Internet.

Nginx come web server, reverse proxy L7/L4 e terminazione TLS

Introduzione

Installazione di Nginx (macOS con Homebrew)

Configurazione minima: web server statico

Servire file statici con root

Più “siti” con blocchi location

Statico da directory esterna con location dedicato

Regex e return per bloccare estensioni

Reverse proxy layer 7 con più backend Node.js

Scenario di esempio

upstream e round-robin

ip_hash e sticky session

Due upstream distinti per /app1 e /app2

Proteggere /admin dal traffico pubblico

Nginx come proxy / load balancer layer 4 (stream)

Differenza concettuale

Esempio di configurazione stream

Esporre Nginx su Internet e DNS

Port forwarding su router

Hostname DNS

TLS con Let’s Encrypt e certbot

Flusso semplificato

Configurazione SSL in Nginx

Abilitare esplicitamente TLS 1.3 e HTTP/2

Riepilogo

Continua la lettura

Servire file statici con `root`

Più “siti” con blocchi `location`

Statico da directory esterna con `location` dedicato

Regex e `return` per bloccare estensioni

`upstream` e round-robin

`ip_hash` e sticky session

Due upstream distinti per `/app1` e `/app2`

Proteggere `/admin` dal traffico pubblico

Nginx come proxy / load balancer layer 4 (`stream`)

Esempio di configurazione `stream`