Crate ngx

Expand description

Bindings to NGINX

This project provides Rust SDK interfaces to the NGINX proxy allowing the creation of NGINX dynamic modules completely in Rust.

§Build

NGINX modules can be built against a particular version of NGINX. The following environment variables can be used to specify a particular version of NGINX or an NGINX dependency:

ZLIB_VERSION (default 1.3.1) - zlib version
PCRE2_VERSION (default 10.42 for NGINX 1.22.0 and later, or 8.45 for earlier) - PCRE1 or PCRE2 version
OPENSSL_VERSION (default 3.2.4 for NGINX 1.22.0 and later, or 1.1.1w for earlier) - OpenSSL version
NGX_VERSION (default 1.26.3) - NGINX OSS version
NGX_DEBUG (default to false) - if set to true, then will compile NGINX --with-debug option

For example, this is how you would compile the examples using a specific version of NGINX and enabling debugging:

NGX_DEBUG=true NGX_VERSION=1.23.0 cargo build --package=examples --examples --release

To build Linux-only modules, use the “linux” feature:

cargo build --package=examples --examples --features=linux --release

After compilation, the modules can be found in the path target/release/examples/ ( with the .so file extension for Linux or .dylib for MacOS).

Additionally, the folder .cache/nginx/{NGX_VERSION}/{TARGET} ({TARGET} means rustc’s target triple string) will contain the compiled version of NGINX used to build the SDK. You can start NGINX directly from this directory if you want to test the module or add it to $PATH

$ export NGX_VERSION=1.23.3
$ cargo build --package=examples --examples --features=linux --release
$ export PATH=$PATH:$PWD/.cache/nginx/$NGX_VERSION/x86_64-unknown-linux-gnu/sbin
$ nginx -V
$ ls -la ./target/release/examples/
# now you can use dynamic modules with the NGINX

The following environment variables can be used to change locations of cache directory and NGINX directory:

CACHE_DIR (default [nginx-sys's root directory]/.cache) - the directory containing cache files, means PGP keys, tarballs, PGP signatures, and unpacked source codes. It also contains compiled NGINX in default configuration.
NGINX_INSTALL_ROOT_DIR (default {CACHE_DIR}/nginx) - the directory containing the series of compiled NGINX in its subdirectories
NGINX_INSTALL_DIR (default {NGINX_INSTALL_BASE_DIR}/{NGX_VERSION}/{TARGET}) - the directory containing the NGINX compiled in the build

§Mac OS dependencies

In order to use the optional GNU make build process on MacOS, you will need to install additional tools. This can be done via homebrew with the following command:

brew install make openssl grep

Additionally, you may need to set up LLVM and clang. Typically, this is done as follows:

# make sure xcode tools are installed
xcode-select --install
# instal llvm
brew install --with-toolchain llvm

§Linux dependencies

See the Dockerfile for dependencies as an example of required packages on Debian Linux.

§Build with external NGINX source tree

If you require a customized NGINX configuration, you can build a module against an existing pre-configured source tree. To do that, you need to set the NGX_OBJS variable to an absolute path of the NGINX build directory (--builddir, defaults to the objs in the source directory). Only the ./configure step of the NGINX build is mandatory because bindings don’t depend on any of the artifacts generated by make.

NGINX_BUILD_DIR=$PWD/../nginx/objs cargo build --package=examples --examples

Furthermore, this approach can be leveraged to build a module as a part of the NGINX build process by adding the --add-module/--add-dynamic-module options to the configure script. See the following example integration scripts: examples/config and examples/config.make.

Modules§

core: The core module.
ffi: The ffi module.
http: The http module.
log: The log module.

Macros§

count: Count number of arguments
http_request_handler: Define a static request handler.
http_subrequest_handler: Define a static post subrequest handler.
http_upstream_init_peer_pt: Define a static upstream peer initializer
http_variable_get: Define a static variable evaluator.
http_variable_set: Define a static variable setter.
ngx_conf_log_error: Write to logger with the context of currently processed configuration file.
ngx_container_of: Gets an outer object pointer from a pointer to one of its fields. While there is no corresponding C macro, the pattern is common in the NGINX source.
ngx_log_debug: Write to logger at debug level.
ngx_log_debug_http: Log to request connection log at level NGX_LOG_DEBUG_HTTP.
ngx_log_debug_mask: Log with requested debug mask.
ngx_log_error: Write to logger at a specified level.
ngx_modules: Define modules exported by this library.
ngx_string: Static string initializer for ngx_str_t.