NGINX Packaging

Overview

Due to the nature of NGINX's module architecture, it is important to understand the intricacies involved in maintaining compatibility across different versions.

Dynamic Modules

When we compile a dynamic module, the raw output is a shared object (.so file). At startup and reload, NGINX loads each of the shared objects named by a load_module directive (which by convention are in the main configuration file, nginx.conf).

Dynamic modules are binary‑compatible with the official builds of NGINX and NGINX Plus. However, this binary compatibility has limitations. Dynamic modules must be compiled against the same version of NGINX they are loaded into. This means that upgrading NGINX without rebuilding all dynamic modules built against the matching version results in a failure during load time.

Distro flags

Due to the default configuration of the NGINX dynamic module configure scripts and Makefile, our distribution's LDFLAGS are ignored. To address this, the configure scripts accept a --with-ld-opt option, allowing you to pass along our distribution's flags. Additionally, for dynamic modules compatibility, the --with-compat option should always be used.

/usr/src/nginx/configure \
    --with-compat \
    --with-ld-opt="${LDFLAGS}" \
    --add-dynamic-module=../modsecurity-nginx-v$pkgver

Depending on nginx

Taking the incompatibility into account, dynamic module packages should depend on the exact nginx version used during compilation to avoid breakage after a systen upgrade in case a rebuild has been missed. To achieve this, the dynamic module packages should makedepends on nginx as well as in their respective package() function add a depends on the precise nginx version:

makedepends=(
  nginx
  nginx-src
)

package() {
  local _nginx_version=$(nginx -v 2>&1)
  _nginx_version=${_nginx_version/* nginx\/}
  depends+=("nginx=${_nginx_version}")
}

Rebuilding packages

The easiest way to find the rebuild targets is to lookout for dependencies on the nginx-src split package, which contains the require source code for dynamic modules to compile against. The rebuild targets can be double checked against the ArchWeb frontend.

Using pkgctl to get a list of packages having a makedepends on nginx-src:

pkgctl search --json '"makedepends = nginx-src"' | jq --raw-output '.[].project_name'

2.5 KiB Raw Permalink Blame History Unescape Escape