diff --git a/README.md b/README.md index 0267ecb..6c8c460 100644 --- a/README.md +++ b/README.md @@ -24,13 +24,47 @@ The module implements following specifications: ### Requirements +- NGINX sources, 1.25.0 or later. - Regular NGINX build dependencies: C compiler, make, PCRE2, Zlib - System-wide installation of OpenSSL 1.1.1 or later - Rust toolchain (1.81.0 or later) +- `pkg-config` or `pkgconf` - [libclang] for rust-bindgen +The NGINX and its dependency versions should match the ones you plan to deploy, +including any patches that change the API. + +> [!TIP] +> The module built against a specific release of unmodified NGINX Open Source +> with `--with-compat --with-http_ssl_module` is compatible with a corresponding +> release of NGINX Plus. +> Refer to https://www.f5.com/company/blog/nginx/compiling-dynamic-modules-nginx-plus + [libclang]: https://rust-lang.github.io/rust-bindgen/requirements.html +#### Important note on SSL libraries + +It is important to ensure that the module uses the same SSL implementation as +NGINX. SSL contexts and certificate objects are passed between the module and +NGINX code, and any mismatches in types can cause memory issues and crashes. + +The best way to guarantee this is to build both with a system-provided shared +library. + +If you absolutely have to use an alternative SSL implementation, ensure that +the module uses it during build by setting appropriate +[`OPENSSL_*` variables](https://docs.rs/openssl/latest/openssl/#manual) for the +Rust bindings to OpenSSL. Check [build-aws-lc.mk](build/build-aws-lc.mk) and +[build-aws-lc-static.mk](build/build-aws-lc-static.mk) CI configurations for +examples. + +Also, note that dynamic build of the module must use dynamic linking for the SSL +library. Static linking in that scenario will result in two copies of the +library code with independent global state. + +See [SSL library compatibility](https://github.com/nginx/nginx-acme/wiki/Compatibility#ssl-libraries) +in the project wiki for the state of support of alternative SSL implementations. + ### Building One way to build the module is to export a path to a configured NGINX source @@ -67,9 +101,9 @@ auto/configure, all the module build-time options are set via environment variables passed to the `cargo build` or `make` commands. Currently accepted options are: - - `NGX_ACME_STATE_PREFIX`: sets a default prefix for per-issuer state paths. - If unset, state paths are created relative to the NGINX prefix directory. - The prefix directory should exist and be readable to the worker processes. +- `NGX_ACME_STATE_PREFIX`: sets a default prefix for per-issuer state paths. + If unset, state paths are created relative to the NGINX prefix directory. + The prefix directory should exist and be readable to the worker processes. Example: @@ -149,6 +183,11 @@ server { ## Directives +> [!IMPORTANT] +> The reference below reflects the current development version. See +> [ngx_http_acme_module](https://nginx.org/en/docs/http/ngx_http_acme_module.html) +> documentation on [nginx.org](https://nginx.org) for the latest released version. + ### acme_issuer **Syntax:** acme_issuer `name` { ... } @@ -259,7 +298,7 @@ Enables or disables verification of the ACME server certificate. **Syntax:** state_path `path` | `off` -**Default:** acme_`name` or `$NGX_ACME_STATE_PREFIX`/acme_`name` +**Default:** acme\_`name` or `$NGX_ACME_STATE_PREFIX`/acme\_`name` **Context:** acme_issuer