proxy_pass con URI non è senza URI

Il 29 ottobre 2026 un proxy_pass con URI non è un proxy_pass senza URI. Sulla pagina del modulo ngx_http_proxy_module, se la direttiva ha un URI, la parte dell’URI di richiesta normalizzato che combacia con la location viene sostituita. Se non ha un URI, la richiesta passa nella forma inviata dal client, oppure passa l’URI normalizzato intero quando l’URI è stato cambiato. Non è un EXPOSE in un Dockerfile: lì si dichiara una porta, qui si decide cosa il backend riceve come percorso.

In breve: l’esempio con URI è proxy_pass http://127.0.0.1/remote/; dentro location /name/. L’esempio senza URI è proxy_pass http://127.0.0.1; dentro location /some/path/. Non ho mandato una richiesta a un nginx: ho letto la pagina del modulo.

Con un URI, una sostituzione

La direttiva proxy_pass ha sintassi proxy_pass URL;, nessun default, contesto location, if in location, limit_except. Imposta protocollo e indirizzo del server proxato e un URI facoltativo a cui mappare la location. Come protocollo la pagina ammette http o https.

Se la direttiva è specificata con un URI, quando la richiesta passa al server la parte dell’URI normalizzato che combacia con la location è sostituita dall’URI della direttiva. L’esempio della pagina è questo:

location /name/ {
    proxy_pass http://127.0.0.1/remote/;
}

La pagina non stampa, sotto l’esempio, una richiesta in ingresso e il percorso che ne esce. Non ne fabbrico una. La regola scritta è la sostituzione della parte che combacia con la location.

Senza URI, un’altra frase

Se proxy_pass è specificato senza un URI, l’URI di richiesta passa al server nella stessa forma inviata dal client quando si elabora la richiesta originale, oppure passa l’URI di richiesta normalizzato per intero quando si elabora l’URI cambiato. L’esempio è:

location /some/path/ {
    proxy_pass http://127.0.0.1;
}

Nell’esempio senza URI non c’è un percorso dopo l’host. Nell’esempio con URI il percorso c’è, /remote/. Non sono due grafie della stessa riga. La pagina non dice che uno slash finale, da solo e in astratto, sia sempre la differenza: mostra questi due casi.

Tre casi in cui la sostituzione non si applica

La pagina elenca casi in cui la parte di URI da sostituire non si può determinare, e altri in cui l’URI della direttiva non fa quello che fa nell’esempio /remote/.

Il primo: location con espressione regolare, e anche le location con nome. In questi casi, scrive la pagina, proxy_pass dovrebbe essere specificato senza un URI.

Il secondo: l’URI viene cambiato dentro la location proxata con rewrite e break. L’esempio riscrive /name/([^/]+) in /users?name=$1 e poi ha proxy_pass http://127.0.0.1;. In questo caso l’URI indicato nella direttiva è ignorato e al server passa l’URI di richiesta cambiato, per intero.

Il terzo: variabili dentro proxy_pass. L’esempio è proxy_pass http://127.0.0.1$request_uri;. Se un URI è specificato nella direttiva, passa al server così com’è e rimpiazza l’URI di richiesta originale. È un’altra frase, non la sostituzione «parte di location contro /remote/».

Prima della 1.1.12

Una nota a parte: prima della versione 1.1.12, se proxy_pass era specificato senza URI, in alcuni casi poteva passare l’URI di richiesta originale invece dell’URI cambiato. È una frase sulla storia del senza-URI. Non è una descrizione del con-URI, e non dice che ogni nginx attuale si comporti come quella versione.

Errori da evitare

• Leggere http://127.0.0.1/remote/ come se fosse http://127.0.0.1. La pagina li mette in due paragrafi diversi, con due regole diverse.

• Inventare l’uscita di un percorso, per esempio «/name/a diventa /remote/a», se la pagina non stampa quell’esempio. La regola c’è. La tabella di input e output, no.

• Mettere un URI in proxy_pass dentro una location regolare o con nome. La pagina dice che in quei casi la direttiva dovrebbe essere senza URI.

• Aspettarsi la sostituzione di /remote/ dopo un rewrite ... break. In quell’esempio l’URI della direttiva è ignorato.

• Trattare $request_uri dentro proxy_pass come l’esempio /remote/. Con le variabili la pagina descrive un passaggio dell’URI così com’è, se un URI è indicato.

• Confondere questa direttiva con EXPOSE di un Dockerfile. Una dichiara una porta nell’immagine. L’altra dice a nginx verso quale URL proxare, e se sostituire il percorso.

In sintesi

Il 29 ottobre 2026 la pagina di proxy_pass distingue una direttiva con URI, che sostituisce la parte di URI normalizzato combaciante con la location, da una direttiva senza URI, che inoltra la forma del client o l’URI normalizzato intero. Gli esempi sono http://127.0.0.1/remote/ e http://127.0.0.1. Location regolari e location con nome vogliono la forma senza URI. Un rewrite con break ignora l’URI della direttiva. Le variabili sono un terzo caso. Prima della 1.1.12 il senza-URI, in alcuni casi, poteva passare l’originale invece del cambiato.

Foto di copertina: Mk2010, «ZyXEL desktop Ethernet switch», Wikimedia Commons, CC BY 4.0. La descrizione del file è uno switch ZyXEL ES-105A a cinque porte, 10/100 Mbps. Non è un file di configurazione nginx e non è la riga proxy_pass.