nginx 1.24 to 1.30: the http2 directive, HTTP/3 and other changes

Between the 1.24 stable branch and 1.30, nginx gained HTTP/3 and a new way to enable HTTP/2. Existing configurations keep working, but nginx -t now warns about the old listen … http2 syntax.

listen … http2 is deprecated

mkdir -p logs temp
openssl req -x509 -newkey rsa:2048 -nodes -keyout key.pem -out cert.pem -days 1 -subj "/CN=localhost" 2>/dev/null
check() {
  cat > nginx.conf <<EOF
pid logs/nginx.pid;
events {}
http { server { $1 ssl_certificate cert.pem; ssl_certificate_key key.pem; } }
EOF
  nginx -p . -c nginx.conf -e stderr -t 2>&1 | sed -E 's/^[0-9/]+ [0-9:]+ \[([a-z]+)\] [0-9#]+: /[\1] /'
}
nginx -v 2>&1
echo "--- old syntax"; check 'listen 127.0.0.1:8443 ssl http2;'
echo "--- new syntax"; check 'listen 127.0.0.1:8443 ssl; http2 on;'

nginx version: nginx/1.30.6
--- old syntax
[warn] the "listen ... http2" directive is deprecated, use the "http2" directive instead in ./nginx.conf:3
nginx: the configuration file ./nginx.conf syntax is ok
nginx: configuration file ./nginx.conf test is successful
--- new syntax
nginx: the configuration file ./nginx.conf syntax is ok
nginx: configuration file ./nginx.conf test is successful

# before (1.24)
listen 443 ssl http2;

# after (1.25.1+)
listen 443 ssl;
http2 on;

Notable changes

Upgrade checklist

1. Run nginx -t with the new binary and fix every [warn].
2. Replace listen … http2 with http2 on; in each server block.
3. For HTTP/3, add listen 443 quic reuseport; next to the TCP listen, open UDP 443 in the firewall, and send add_header Alt-Svc 'h3=":443"; ma=86400';.
4. Check that third-party modules are rebuilt for the new version; dynamic modules must match the exact nginx version.