Enabling HTTP/2 on Tomcat 10: A Practical Step‑by‑Step Guide

Desired Outcome

Configure Tomcat 10 to serve HTTPS requests over HTTP/2, improving latency and resource usage for modern browsers while maintaining backward compatibility with HTTP/1.1 clients.

Prerequisites

• Tomcat 10.x installed (10.0 or later).
• Java 11+ (Java 8 requires the alpn‑boot agent).
• Valid TLS certificate and private key for the HTTPS connector.
• Administrative access to the Tomcat installation directory.
• Firewall rules allowing inbound traffic on the HTTPS port (default 443 or 8443).

Focused Procedure

1. Backup the Current Configuration

   Before editing server.xml, make a copy:

   sudo cp $CATALINA_HOME/conf/server.xml $CATALINA_HOME/conf/server.xml.bak
   

2. Locate or Add the HTTPS Connector

   Open server.xml in your preferred editor. Find the existing HTTPS connector or add a new one:

   <Connector port="8443" protocol="org.apache.coyote.http11.Http11Nio2Protocol" \
              scheme="https" secure="true" SSLEnabled="true" \
              sslProtocol="TLS" alpnProtocols="h2"/>
   

   Key attributes:

   • protocol must be org.apache.coyote.http11.Http11Nio2Protocol – HTTP/2 is only supported on the NIO2 connector.
   • alpnProtocols="h2" enables ALPN negotiation for HTTP/2.
   • Ensure SSLEnabled="true" and a valid sslProtocol (TLS 1.2+ recommended).

3. Restart Tomcat

   Apply the changes by restarting the server. Use the method appropriate for your environment:

   # Systemd
   sudo systemctl restart tomcat
   
   # Stand‑alone script
   $CATALINA_HOME/bin/shutdown.sh
   $CATALINA_HOME/bin/startup.sh
   

   Check the startup logs for a line similar to HTTP/2 enabled for connector [https] to confirm the connector activated without errors.

4. Validate the HTTP/2 Handshake

   Run curl from a machine that supports HTTP/2 and ALPN:

   curl --http2 -v https://localhost:8443/ -o /dev/null
   

   Expected output (simplified):

   *   Trying 127.0.0.1:8443...
   * Connected to localhost (127.0.0.1) port 8443 (#0)
   * ALPN: h2
   * SSL handshake using TLSv1.3
   *   ...
   > GET / HTTP/2
   > Host: localhost
   > ...
   * HTTP/2 200
   * Connection #0 to host localhost left intact
   

   Key indicators:

   • The ALPN line shows h2.
   • The request line starts with GET / HTTP/2.
   • The status line begins with HTTP/2 200.

5. Verify in a Browser

   Open a modern browser (Chrome ≥ 61, Edge ≥ 12, Safari ≥ 10). Navigate to https://localhost:8443/. Open DevTools, go to the Network tab, and inspect the request. The Protocol column should display h2. If you see http/1.1, HTTP/2 was not negotiated.

6. Check Tomcat Logs for Errors

   Inspect catalina.out or the equivalent log file for messages such as ALPN not supported or Failed to bind. These indicate that the JVM or network configuration prevented HTTP/2 from starting.

Recovery Options

• If the connector fails to start, revert to the backup configuration:

  sudo cp $CATALINA_HOME/conf/server.xml.bak $CATALINA_HOME/conf/server.xml
  sudo systemctl restart tomcat
  

• To disable HTTP/2 temporarily, comment out or remove the alpnProtocols="h2" attribute. Tomcat will default to HTTP/1.1 on the same connector.
• When using a reverse proxy that terminates TLS, ensure the proxy forwards the ALPN extension. Without it, Tomcat will not negotiate HTTP/2 even if the connector is configured correctly.

Limitations & Practical Checks

• HTTP/2 requires TLS; plain HTTP on port 80 will never negotiate HTTP/2.
• Java 8 does not ship with ALPN support. Either upgrade to Java 11+ or add the alpn‑boot agent, but note that the agent is no longer maintained.
• Older browsers will automatically fall back to HTTP/1.1; the absence of HTTP/2 in DevTools does not indicate a failure.
• Verify that the cipher suite chosen for TLS supports ALPN; some legacy suites may cause a handshake failure.
• Network firewalls must allow inbound traffic on the HTTPS port. A blocked port will mask the HTTP/2 configuration as a connectivity issue.

Practical Result Check

After completing the steps, run the following test from a client machine to confirm end‑to‑end success:

curl --http2 -v https://localhost:8443/ | grep -i "HTTP/2"

If the output contains HTTP/2 200 and the ALPN line shows h2, the configuration is correct. Otherwise, review the logs and ensure the JVM version and TLS settings meet the prerequisites.