  MOD_HTTP3 INSTALLATION


  Build
  -----

  Default build compiles all dependencies from submodules:

     $ git submodule update --init --recursive
     $ cmake -B build
     $ cmake --build build

  To use system-installed dependencies, provide WITH_* paths:

     $ git submodule update --init dependencies/nghttp3
     $ cmake -B build \
         -DWITH_SSL=/opt/openssl \
         -DWITH_HTTPD=/opt/httpd \
         -DBUILD_EXAMPLES=OFF \
         -DBUILD_TESTS=OFF
     $ cmake --build build

  If APR and APR-util are installed separately from httpd:

     $ cmake -B build \
         -DWITH_SSL=/opt/openssl \
         -DWITH_HTTPD=/opt/httpd \
         -DWITH_APR=/opt/apr \
         -DWITH_APU=/opt/apr-util \
         -DBUILD_EXAMPLES=OFF \
         -DBUILD_TESTS=OFF
     $ cmake --build build

  Output: build/lib/mod_http3.so

  Requirements:

     OpenSSL >= 3.5.0 (with QUIC support)
     httpd    MMN >= 20211221
     APR      >= 1.7.0
     APU      >= 1.6.0
     nghttp3  >= 1.18.0

  NOTE: Distro-packaged httpd (Ubuntu, Fedora, etc.) ships with an
  older MMN and will be rejected. Use the default source build or
  provide a custom prefix install via WITH_HTTPD instead.


   Package and Install
   -------------------

   CMake's normal install target intentionally excludes distribution layouts.
   To build binary packages locally:

      $ cmake -B build -DCMAKE_BUILD_TYPE=Release
      $ cmake --build build --target release

   The packages are written to build/dist/:

      mod_http3-X.Y.Z-linux-<arch>.tar.gz
      mod_http3-X.Y.Z-linux-<arch>.zip
      mod_http3-X.Y.Z.<arch>.rpm
      mod_http3_X.Y.Z_<arch>.deb

   Verify a downloaded or locally built artifact with its matching checksum:

      $ (cd build/dist && sha256sum -c mod_http3-X.Y.Z-linux-<arch>.tar.gz.sha256)

   Install the generic Linux archive under a chosen prefix:

      $ sudo mkdir -p /opt/mod_http3
      $ sudo tar -xzf build/dist/mod_http3-X.Y.Z-linux-<arch>.tar.gz -C /opt/mod_http3

   Alternatively, install the native package for the target system:

      $ sudo dnf install build/dist/mod_http3-X.Y.Z.<arch>.rpm
      $ sudo apt install ./build/dist/mod_http3_X.Y.Z_<arch>.deb

   These native packages require a custom httpd with MMN >= 20211221. They are
   not (yet) compatible with stock Apache/httpd 2.4 packages supplied by distributions.


  Deploy into httpd
  -----------------

  1. Copy the module:

     $ cp build/lib/mod_http3.so /path/to/httpd/modules/

  2. Generate a certificate:

     $ bash scripts/mkcert.sh /path/to/httpd/conf/certs
       Generated:
         CA key      : /path/to/httpd/conf/certs/ca.key
         CA crt      : /path/to/httpd/conf/certs/ca.crt
         private key : /path/to/httpd/conf/certs/server.key
         public  crt : /path/to/httpd/conf/certs/server.crt

     The script mints a local CA and signs the leaf with it; browsers
     reject a directly-trusted self-signed leaf. Import ca.crt to trust
     the server. The script refuses to overwrite existing keys.

     The key must be readable by the httpd child user:

     $ chgrp daemon /path/to/httpd/conf/certs/server.key
     $ chmod 640  /path/to/httpd/conf/certs/server.key

  3. Configure httpd.

     LoadModule must appear before the <VirtualHost> block.
     H3CertificatePath and H3CertificateKeyPath are required.

     Minimal httpd.conf:

        LoadModule ssl_module     modules/mod_ssl.so
        LoadModule http3_module   modules/mod_http3.so

        EnableMMAP Off

        Listen 4433 https

        <VirtualHost *:4433>
            ServerName localhost

            SSLEngine on
            SSLCertificateFile    conf/certs/server.crt
            SSLCertificateKeyFile conf/certs/server.key

            H3CertificatePath    conf/certs/server.crt
            H3CertificateKeyPath conf/certs/server.key

            DocumentRoot htdocs
            <Directory htdocs>
                Require all granted
            </Directory>
        </VirtualHost>

      EnableMMAP is fully supported. All data and memory-mapped buckets
      are parsed and processed transparently by mod_http3.

     mod_http3 injects the Alt-Svc response header automatically
     (H3AltSvc, on by default). That header is how TCP clients
     learn HTTP/3 is available on UDP. See docs/configuration_httpd.md
     for H3AltSvc, H3AltSvcMaxAge, and the other H3* directives.

  4. Open the UDP port:

     # red hat:
     $ firewall-cmd --permanent --add-port=4433/udp && firewall-cmd --reload
     # ubuntu:
     $ ufw allow 4433/udp

  5. Validate and start:

     $ /path/to/httpd/bin/httpd -t            # must print "Syntax OK"
     $ /path/to/httpd/bin/httpd -D FOREGROUND -f conf/httpd.conf

  6. Verify:

     $ /path/to/httpd/bin/httpd -M | grep http3
       http3_module (shared)

     $ ss -ulnp | grep 4433
       UNCONN 0 0 :::4433 :::* users:(("httpd",...))

     If the UDP socket is absent but the module is loaded, check
     the error log:

     $ tail -50 /path/to/httpd/logs/error_log | grep -i "http3\|quic"


  Further reading
  ---------------

  docs/configuration.md       - Advanced build options
  docs/configuration_httpd.md - httpd directive reference
