modules.yaml

# modules.yaml: source of truth for blendbyte/nginx-modules
#
# This file defines what gets built. All downstream automation (build
# scripts, CI workflows, package metadata) reads from here. Editing
# this file is the canonical way to add a module, bump a version, or
# change packaging.
#
# config:                    Build configuration (single section)
#   nginx_track              "stable" or "mainline". We ship stable only
#   debian_codenames          List of Debian releases to build for
#   architectures             List of dpkg architectures to build for
#   maintainer                Who appears in debian/control Maintainer field
#   homepage                  Project URL for debian/control
#   archive_url               Public APT URL (informational)
#
# modules:                   List of packages to build. One entry = one .deb.
#                            Some upstreams produce multiple packages from
#                            one source (brotli → filter+static, geoip2 →
#                            http+stream); these are separate entries that
#                            share an upstream_url.
#
#   name                     Debian package name
#   description              One-line description for debian/control
#   upstream_url             Git repository URL
#   upstream_ref             Tag name OR "master" for branch tip.
#                            Resolved to a commit hash by build script;
#                            the resolved hash is recorded in the
#                            generated .deb's debian/changelog.
#   upstream_version         Human-readable version for the version string
#                            (e.g. "0.39", "3.4"). Forks without releases
#                            use a synthetic version with the upstream
#                            commit date appended.
#   packaging_revision       Integer; bump when packaging changes (debian/
#                            rules, postinst, deps) without an upstream
#                            change. Reset to 1 when upstream_version
#                            changes.
#   replaces                 Sury package name this replaces, or null.
#                            Generates Replaces/Conflicts/Provides in
#                            debian/control for seamless migration.
#   module_so                Filename of the produced .so module
#   nginx_context            "http" or "stream"
#   submodules               Use --recurse-submodules on git clone
#   build_deps               Debian build-time dependencies
#   runtime_deps             Debian runtime dependencies
#   load_order               Numeric prefix for the symlink in
#                            /etc/nginx/modules-enabled/. Lower = loaded
#                            earlier. ModSecurity uses 10 (WAF runs
#                            before everything); most modules use 50.
#   license                  SPDX identifier
#   homepage                 Upstream project URL for debian/control
#   notes                    Why we picked this fork and any quirks
#
# ─── Versioning ─────────────────────────────────────────────────────
#
# Generated package version string:
#   {upstream_version}-{packaging_revision}+nginx{nginx_version}+blendbyte{build_serial}~{codename}
#
# Example: nginx-module-brotli for nginx 1.30.0 on Bookworm:
#   1.0.0-1+nginx1.30.0+blendbyte1~bookworm
#
# build_serial is computed by CI from .build-serials at repo root
# and is bumped only when re-publishing the same (module, upstream_ref,
# packaging_revision, nginx_version, codename) combination.

config:
  nginx_track: stable
  debian_codenames:
    - bookworm
    - trixie
  ubuntu_codenames:
    - jammy
    - noble
    - resolute
  architectures:
    - amd64
    - arm64
  maintainer: "Blendbyte <apt@blendbyte.com>"
  homepage: "https://github.com/blendbyte/nginx-modules"
  archive_url: "https://apt.blendbyte.net/nginx"

modules:

  # ─── Compression ──────────────────────────────────────────────────

  - name: nginx-module-brotli
    description: "Brotli compression filter module for nginx"
    upstream_url: https://github.com/nginx-modules/ngx_brotli.git
    upstream_ref: master  # nginx-modules fork has no formal release tags
    upstream_version: "1.0.0"  # synthetic; bump build_serial on master commits
    packaging_revision: 2
    replaces: libnginx-mod-http-brotli-filter
    module_so: ngx_http_brotli_filter_module.so
    nginx_context: http
    submodules: false  # system libbrotli used; bundled submodule not needed
    build_deps:
      - libbrotli-dev
    runtime_deps:
      - libbrotli1
    load_order: 50
    license: BSD-2-Clause
    homepage: https://github.com/nginx-modules/ngx_brotli
    # Patch notes:
    # - sed: ngx_brotli's config searches /usr/local/include/brotli/encode.h for
    #   a system libbrotli, falling back to the bundled v1.0.4 submodule. On
    #   Debian/Ubuntu, libbrotli-dev installs to /usr/include, so the check
    #   always fails and the old bundled library is used. libbrotli 1.0.4 has a
    #   streaming encoder bug at quality 3: BROTLI_OPERATION_FINISH does not
    #   fully finalize the stream in one call for the non-block-split code path
    #   (quality < 4), producing a truncated brotli frame that decompressors
    #   reject. System libbrotli 1.0.9 (shipped on all our target distros) has
    #   this fixed. Change the search path from /usr/local to /usr so the config
    #   finds the system library and links against it (-lbrotlienc) instead of
    #   compiling the buggy bundled source.
    patches:
      - file: config
        sed: 's|brotli="/usr/local"|brotli="/usr"|'
    notes: |
      google/ngx_brotli has gone effectively dormant. Last meaningful
      commit predates 2024, and eustas/ngx_brotli (the lead's own fork)
      was publicly archived. The nginx-modules community fork is the
      maintained successor.

      Previously bundled libbrotli v1.0.4 via git submodule. Switched to
      system libbrotli (libbrotli-dev / libbrotli1) to fix a quality-3
      streaming truncation bug present in the bundled v1.0.4 encoder but
      fixed in v1.0.9 (shipped on all target distros). The ngx_brotli
      config already supports system libbrotli via -lbrotlienc; it only
      needed the search path corrected from /usr/local to /usr.

  - name: nginx-module-brotli-static
    description: "Brotli static-precompressed-files module for nginx"
    upstream_url: https://github.com/nginx-modules/ngx_brotli.git
    upstream_ref: master
    upstream_version: "1.0.0"
    packaging_revision: 2
    replaces: libnginx-mod-http-brotli-static
    module_so: ngx_http_brotli_static_module.so
    nginx_context: http
    submodules: false  # system libbrotli used; bundled submodule not needed
    build_deps:
      - libbrotli-dev  # needed at build time even though static .so doesn't link it
    runtime_deps: []   # static module serves pre-compressed files; no libbrotli at runtime
    load_order: 50
    license: BSD-2-Clause
    homepage: https://github.com/nginx-modules/ngx_brotli
    patches:
      - file: config
        sed: 's|brotli="/usr/local"|brotli="/usr"|'
    notes: |
      Same source as nginx-module-brotli, different .so artifact.
      The static module only serves pre-compressed .br files; it has no
      encoder dependency. libbrotli-dev is still required at build time
      because the shared config builds both .so files in one make run.

  - name: nginx-module-zstd
    description: "Zstandard compression filter module for nginx"
    upstream_url: https://github.com/tokers/zstd-nginx-module.git
    upstream_ref: "0.1.1"
    upstream_version: "0.1.1"
    packaging_revision: 2
    replaces: null
    module_so: ngx_http_zstd_filter_module.so
    nginx_context: http
    submodules: false
    build_deps:
      - libzstd-dev
    runtime_deps:
      - libzstd1
    load_order: 50
    license: BSD-2-Clause
    homepage: https://github.com/tokers/zstd-nginx-module
    # Patch notes:
    # - sed: filter/config and static/config hardcode -l:libzstd.a (static
    #   linking). The system libzstd.a on Debian isn't built with -fPIC, so
    #   linking it into a .so fails on aarch64 ("relocation R_AARCH64_ADR_PREL
    #   _PG_HI21 ... can not be used when making a shared object"). Switch to
    #   dynamic linking; libzstd1 is in runtime_deps. (The top-level config
    #   just sources the two subconfigs, so patching it directly does nothing.)
    # - fix-filter-bugs-pr23-pr49.patch: two unmerged upstream bug fixes:
    #   PR#23 infinite loop when upstream sends Content-Length > actual body;
    #   PR#49 silent truncation of responses > 131072 bytes (ZSTD_CStreamInSize)
    #   due to premature last_buf=1 before ZSTD_endStream has run.
    # - fix-brotli-ordering-pr44.patch: run zstd before brotli when both are
    #   loaded (combined with the module-order fix from master commit f4ba115e,
    #   never tagged). Without this, clients that support both always get brotli.
    # - fix-encoding-check-pr43.patch: three bugs in Accept-Encoding handling:
    #   (1) h->next not zeroed on nginx >= 1.23.0 (stale pointer in header list);
    #   (2) zstd;q=0 (RFC 7231 "do not compress") was ignored;
    #   (3) static module ngx_strcasestrn off-by-one (sizeof-1 vs sizeof-2)
    #   that caused "gzip, zstd, br" style headers (zstd mid-list) to never
    #   match; only a leading or trailing zstd token worked. Extracts shared
    #   check_request() into common/ used by both filter and static modules.
    patches:
      - file: filter/config
        sed: 's|-l:libzstd\.a|-lzstd|g'
      - file: static/config
        sed: 's|-l:libzstd\.a|-lzstd|g'
      - patch: patches/nginx-module-zstd/fix-filter-bugs-pr23-pr49.patch
      - patch: patches/nginx-module-zstd/fix-brotli-ordering-pr44.patch
      - patch: patches/nginx-module-zstd/fix-encoding-check-pr43.patch
    notes: |
      Upstream (tokers/zstd-nginx-module) is lightly maintained; critical bug
      fixes are applied as patches from unmerged PRs. See patch comments above.

  - name: nginx-module-modsecurity
    description: "ModSecurity v3 connector for nginx (WAF)"
    upstream_url: https://github.com/owasp-modsecurity/ModSecurity-nginx.git
    upstream_ref: master
    upstream_version: "1.0.4"
    packaging_revision: 1
    replaces: null
    module_so: ngx_http_modsecurity_module.so
    nginx_context: http
    submodules: false
    build_deps:
      - libmodsecurity-dev
    runtime_deps:
      - libmodsecurity3
    patches:
      - file: config
        sed: 's@ngx_feature_libs="-lmodsecurity"@ngx_feature_libs="-lmodsecurity $(pkg-config --libs libpcre 2>/dev/null || true)"@g'
    load_order: 10  # Load early. WAF runs before other filters
    license: Apache-2.0
    homepage: https://github.com/owasp-modsecurity/ModSecurity-nginx
    notes: |
      Just the connector. libmodsecurity3 itself comes from Debian
      (Bookworm has 3.0.6, Trixie has 3.0.12). The project moved from
      Trustwave SpiderLabs to OWASP in February 2024; this is the
      canonical home now. OWASP CRS rules aren't packaged here, grab
      those from coreruleset.org.
      The pkg-config patch conditionally adds -lpcre at build time. On
      bookworm/jammy/noble, libmodsecurity3 was compiled with a PCRE1 compat
      shim and exports pcre_malloc as an undefined symbol expected from the
      caller; nginx.org's PCRE2 nginx doesn't supply it, so we link the
      connector against libpcre.so.3 explicitly. On trixie/resolute, PCRE1
      is absent and libmodsecurity3 no longer has this dependency, so
      pkg-config returns nothing and no -lpcre is added.
      See: https://github.com/blendbyte/nginx-modules/issues/3

  - name: nginx-module-zstd-static
    description: "Zstandard static precompressed files module for nginx"
    upstream_url: https://github.com/tokers/zstd-nginx-module.git
    upstream_ref: "0.1.1"
    upstream_version: "0.1.1"
    packaging_revision: 1
    replaces: null
    module_so: ngx_http_zstd_static_module.so
    nginx_context: http
    submodules: false
    build_deps:
      - libzstd-dev
    runtime_deps:
      - libzstd1
    load_order: 50
    license: BSD-2-Clause
    homepage: https://github.com/tokers/zstd-nginx-module
    patches:
      - file: filter/config
        sed: 's|-l:libzstd\.a|-lzstd|g'
      - file: static/config
        sed: 's|-l:libzstd\.a|-lzstd|g'
      - patch: patches/nginx-module-zstd/fix-encoding-check-pr43.patch
    notes: |
      Same source as nginx-module-zstd; serves pre-compressed .zst files
      (analogous to gzip_static / ngx_http_brotli_static_module).
      Both subconfigs are patched for the same -fPIC / static-lib reason
      as the filter module.

  - name: nginx-module-geoip2
    description: "MaxMind GeoIP2 lookup module for nginx (HTTP)"
    upstream_url: https://github.com/leev/ngx_http_geoip2_module.git
    upstream_ref: "3.4"
    upstream_version: "3.4"
    packaging_revision: 2
    replaces: libnginx-mod-http-geoip2
    module_so: ngx_http_geoip2_module.so
    nginx_context: http
    submodules: false
    build_deps:
      - libmaxminddb-dev
    runtime_deps:
      - libmaxminddb0
    load_order: 50
    license: BSD-2-Clause
    homepage: https://github.com/leev/ngx_http_geoip2_module
    # fix-stale-address-on-reload-pr135.patch: after MMDB auto_reload, the
    # per-database cached address wasn't cleared. The next request from the
    # same IP hit the cache and used database->result, which holds pointers
    # into the old (now closed/unmapped) MMDB - stale or garbage geo data.
    # Fix: zero database->address after the mmdb swap to force a fresh lookup.
    patches:
      - patch: patches/nginx-module-geoip2/fix-stale-address-on-reload-pr135.patch
    notes: |
      Original maintainer, small and stable since 2022. GeoLite2 .mmdb
      database files aren't bundled, you'll have to grab them from
      MaxMind directly (free signup required since 2019). Set up
      geoipupdate to keep them fresh.

  - name: nginx-module-stream-geoip2
    description: "MaxMind GeoIP2 lookup module for nginx (Stream/TCP/UDP)"
    upstream_url: https://github.com/leev/ngx_http_geoip2_module.git
    upstream_ref: "3.4"
    upstream_version: "3.4"
    packaging_revision: 2
    replaces: libnginx-mod-stream-geoip2
    module_so: ngx_stream_geoip2_module.so
    nginx_context: stream
    submodules: false
    build_deps:
      - libmaxminddb-dev
    runtime_deps:
      - libmaxminddb0
    load_order: 50
    license: BSD-2-Clause
    homepage: https://github.com/leev/ngx_http_geoip2_module
    patches:
      - patch: patches/nginx-module-geoip2/fix-stale-address-on-reload-pr135.patch
    notes: |
      Same source as nginx-module-geoip2; stream-context variant.

  - name: nginx-module-headers-more
    description: "Set, add, and clear arbitrary output headers in nginx"
    upstream_url: https://github.com/openresty/headers-more-nginx-module.git
    upstream_ref: "v0.40"
    upstream_version: "0.40"
    packaging_revision: 1
    replaces: libnginx-mod-http-headers-more-filter
    module_so: ngx_http_headers_more_filter_module.so
    nginx_context: http
    submodules: false
    build_deps: []
    runtime_deps: []
    load_order: 50
    license: BSD-2-Clause
    homepage: https://github.com/openresty/headers-more-nginx-module
    notes: |
      Active maintenance; v0.40 released 2026-05-12. OpenResty team.
      v0.40 fixes an OOB read in Content-Type charset parsing (missing
      end-pointer guard in the ';' scan) and a per-header is_builtin_header
      flag that wasn't reset between headers in the same more_set_headers
      directive, causing incorrect handler dispatch for later headers.

  - name: nginx-module-substitutions
    description: "Regex and string substitutions in response bodies for nginx"
    upstream_url: https://github.com/yaoweibin/ngx_http_substitutions_filter_module.git
    upstream_ref: master
    upstream_version: "0.6.4"
    packaging_revision: 2
    replaces: libnginx-mod-http-subs-filter
    module_so: ngx_http_subs_filter_module.so
    nginx_context: http
    submodules: false
    build_deps: []
    runtime_deps: []
    patches:
      - file: config
        sed: 's@ngx_module_libs=""@ngx_module_libs="$(pkg-config --libs libpcre 2>/dev/null || true)"@g'
      - patch: patches/nginx-module-substitutions/fix-null-check-init-context.patch
    load_order: 50
    license: BSD-2-Clause
    homepage: https://github.com/yaoweibin/ngx_http_substitutions_filter_module
    notes: |
      No new releases since 0.6.4 in 2014, but the master branch is
      maintained (PR #19 added dynamic module support in Aug 2019, plus
      occasional fixes for newer nginx ABIs). The "nginx-modules" fork
      that's often referenced online is actually a stale 2014 mirror
      that doesn't have the dynamic module fix.
      The pkg-config patch conditionally links against libpcre.so.3 on
      bookworm/jammy/noble where nginx.org's PCRE2 nginx does not export
      PCRE1 symbols (pcre_fullinfo etc.) that this module uses directly.

  - name: nginx-module-cache-purge
    description: "Purge content from FastCGI/proxy/SCGI/uWSGI caches in nginx"
    upstream_url: https://github.com/nginx-modules/ngx_cache_purge.git
    upstream_ref: master
    upstream_version: "2.5.6"
    packaging_revision: 1
    replaces: libnginx-mod-http-cache-purge
    module_so: ngx_http_cache_purge_module.so
    nginx_context: http
    submodules: false
    build_deps: []
    runtime_deps: []
    load_order: 50
    license: BSD-2-Clause
    homepage: https://github.com/nginx-modules/ngx_cache_purge
    notes: |
      FRiCKLE original frozen at v2.3 (2014). nginx-modules community fork
      carries patches needed for nginx 1.18+.

  - name: nginx-module-fancyindex
    description: "Fancy directory listing module for nginx"
    upstream_url: https://github.com/aperezdc/ngx-fancyindex.git
    upstream_ref: "v0.5.2"
    upstream_version: "0.5.2"
    packaging_revision: 2
    replaces: libnginx-mod-http-fancyindex
    module_so: ngx_http_fancyindex_module.so
    nginx_context: http
    submodules: false
    build_deps: []
    runtime_deps: []
    load_order: 50
    license: BSD-2-Clause
    homepage: https://github.com/aperezdc/ngx-fancyindex
    # fix-fd-leak-local-headerfooter-pr176.patch: ngx_fancyindex_conf_set_headerfooter()
    # closes file.fd on all error paths but omits the close on the successful read path.
    # Each nginx reload retains one fd per local header/footer directive, eventually
    # exhausting the process fd limit (EMFILE / accept4() failures). One-line fix from
    # upstream PR#176; present in v0.5.2 and v0.6.0.
    patches:
      - patch: patches/nginx-module-fancyindex/0001-close-fd-on-successful-local-headerfooter-read.patch
    notes: |
      Original maintainer (aperezdc) is active via master commits between
      tagged releases. Pin to v0.5.2 tag for now; consider bumping to a
      specific master commit if a needed fix lands.

  - name: nginx-module-dav-ext
    description: "Extended WebDAV methods (PROPFIND, OPTIONS, LOCK, UNLOCK) for nginx"
    upstream_url: https://github.com/arut/nginx-dav-ext-module.git
    upstream_ref: "v3.0.0"
    upstream_version: "3.0.0"
    packaging_revision: 1
    replaces: libnginx-mod-http-dav-ext
    module_so: ngx_http_dav_ext_module.so
    nginx_context: http
    submodules: false
    build_deps:
      - libxml2-dev
      - libxslt1-dev
    runtime_deps: []
    load_order: 50
    license: BSD-2-Clause
    homepage: https://github.com/arut/nginx-dav-ext-module
    notes: |
      Maintained by Roman Arutyunyan, an F5/nginx core engineer. Requires
      nginx built with --with-http_dav_module. Official nginx.org packages
      include this. Stable codebase, slow release cadence.