Set Up an SNI Proxy on Debian 13 With Nginx Stream (ssl_preread)
Route HTTPS connections to different backends by their SNI host name on Debian 13 with Nginx's stream module, and see where the deprecated sniproxy still fits.
An SNI proxy reads the host name that a TLS client sends in its first packet (the Server Name Indication) and forwards the still-encrypted connection to the backend responsible for that name. Several HTTPS sites on different servers can then share one public IP address, and the proxy never needs their certificates or private keys. This guide builds such a proxy on Debian 13 (trixie) with the Nginx stream module and its ssl_preread feature; the steps also apply to Debian 12 (bookworm).
Status of the sniproxy project
The original tool for this job, sniproxy by Dustin Lundquist, was marked deprecated by its author in December 2023. The project's README explains that other proxies, including Nginx, now cover this use case, that sniproxy does not support HTTP/2 multiplexing of several host names over one connection or HTTP/3 (QUIC), and that only significant security or reliability issues will get a response. Debian still packages it for Debian 12 and 13, so there is no need to compile it from source as older tutorials did. For a new setup, use Nginx: it is actively developed and does the same routing. A short sniproxy section near the end covers the case where you must keep an existing configuration running.
Requirements
- A Debian 13 or Debian 12 server with a public IP address that will act as the proxy, and a user with
sudorights. - Backend servers that already serve HTTPS with their own certificates (examples:
203.0.113.10and203.0.113.20). - DNS records for the proxied host names (
app.example.com,shop.example.com) pointing to the proxy's IP address. - Port 443 free on the proxy. If a web server on the same machine already listens on 443, move it to another port first (see below).
Install Nginx and the stream module
Debian ships the stream module as a separate dynamic module package:
sudo apt update
sudo apt install nginx libnginx-mod-streamConfirm that the module is enabled and that SNI pre-reading was compiled in:
ls /etc/nginx/modules-enabled/
sudo nginx -V 2>&1 | tr ' ' '\n' | grep streamThe first command should list a stream module file, and the second should include --with-stream_ssl_preread_module. Without that option the ssl_preread directive is not available.
Create the SNI routing configuration
A stream block must sit at the top level of the Nginx configuration, next to the http block, not inside it. Files in /etc/nginx/conf.d/ and /etc/nginx/sites-enabled/ are included from inside http in Debian's default nginx.conf, so they are the wrong place. Create a separate file:
sudo nano /etc/nginx/stream.confstream {
# Choose a backend from the SNI name in the TLS ClientHello
map $ssl_preread_server_name $tls_backend {
app.example.com 203.0.113.10:443;
shop.example.com 203.0.113.20:443;
~\.example\.net$ 203.0.113.20:443;
default 127.0.0.1:8443;
}
server {
listen 443;
listen [::]:443;
ssl_preread on;
proxy_pass $tls_backend;
}
}What the directives do:
ssl_preread onmakes Nginx extract information from the ClientHello message without terminating TLS and fills the variable$ssl_preread_server_name.- The
mapblock translates that name to a backend address. A line starting with~is a regular expression, here matching every host underexample.net. defaultcatches clients that send no SNI or an unknown name. Point it at a local web server, or at a port where nothing listens if you want those connections to fail.
Now include the file from the main configuration. Open /etc/nginx/nginx.conf and add this line at the very end, after the closing brace of the http block:
include /etc/nginx/stream.conf;If Nginx also serves websites on the same machine
Only one listener can own port 443. Change the listen 443 ssl; lines of the local sites in /etc/nginx/sites-available/ to a loopback port, and let the stream block forward to it through the default entry or an explicit map line:
listen 127.0.0.1:8443 ssl;Test and reload
sudo nginx -t
sudo systemctl reload nginxCheck that Nginx is listening on port 443:
sudo ss -tlnp | grep ':443'From another machine, connect through the proxy with different SNI names and confirm that each backend answers with its own certificate. Replace 198.51.100.5 with the proxy's public address:
openssl s_client -connect 198.51.100.5:443 -servername app.example.com </dev/null 2>/dev/null | openssl x509 -noout -subject
openssl s_client -connect 198.51.100.5:443 -servername shop.example.com </dev/null 2>/dev/null | openssl x509 -noout -subjectIf a firewall runs on the proxy, allow inbound TCP 443 and outbound connections to the backends.
Pass the client address to the backends
Because the proxy forwards raw TCP, backends see the proxy's IP address as the client. If you need the real address in backend logs, enable the PROXY protocol towards the backends by adding this line inside the stream server block:
proxy_protocol on;Every backend must then be configured to expect the PROXY protocol header on that port (in Nginx, the proxy_protocol parameter of listen). Enable it on both sides at the same time; a backend that does not expect the header will not understand the connection.
What about port 80?
Plain HTTP has no SNI, so the stream module cannot route it by host name. The ordinary http part of Nginx can. The simplest approach on a dedicated proxy is to redirect everything to HTTPS. Remove Debian's default site and create a redirect:
sudo rm /etc/nginx/sites-enabled/default
sudo nano /etc/nginx/conf.d/redirect.confserver {
listen 80 default_server;
listen [::]:80 default_server;
return 301 https://$host$request_uri;
}Run sudo nginx -t and reload again. If the backends obtain certificates with an HTTP-based challenge on port 80, proxy those requests to them by host name with regular proxy_pass rules instead of redirecting.
Keeping an existing sniproxy setup
If you need the original tool, install the Debian package and edit /etc/sniproxy.conf:
sudo apt install sniproxy
sudo nano /etc/sniproxy.confuser daemon
pidfile /var/run/sniproxy.pid
error_log {
syslog daemon
priority notice
}
listen 443 {
proto tls
table https_hosts
}
table https_hosts {
app.example.com 203.0.113.10:443
shop.example.com 203.0.113.20:443
}Table patterns are regular expressions, and a target of * means "connect to the host name the client asked for". Restart and check the service:
sudo systemctl restart sniproxy
systemctl status sniproxyTreat this as a stopgap and plan the move to Nginx. Reference documentation: the Nginx ngx_stream_ssl_preread_module page and the sniproxy repository.
Frequently asked questions
Does the proxy need the sites' TLS certificates?
No. The connection is forwarded encrypted and the TLS handshake happens between the client and the backend. Certificates and private keys stay on the backends, which also means the proxy cannot inspect, cache or modify the HTTP traffic.
Does this work with HTTP/3?
No. HTTP/3 runs over QUIC on UDP, and ssl_preread reads the ClientHello of TLS connections over TCP. Clients use HTTP/2 or HTTP/1.1 over TCP as long as the backends do not advertise HTTP/3 for these host names.
Can a browser end up on the wrong backend?
It can if two host names that route to different backends are covered by the same certificate. With HTTP/2 a browser may reuse an existing connection for the second name, and an SNI-based proxy only sees the name from the start of that connection. Use separate certificates for names served by different backends.
What happens when the client sends no SNI?
$ssl_preread_server_name is empty and the default line of the map decides where the connection goes.