Index of /files/

# https://en.angie.software/angie/docs.md # About Angie Angie /[andʒi](https://en.wikipedia.org/wiki/International_Phonetic_Alphabet)/ is an efficient, powerful, and scalable web server that was forked from nginx: * Conceived by ex-devs from the original team to venture beyond the earlier vision and act as a [drop-in replacement](https://en.angie.software//angie/docs/configuration/migration.md#migration) without major changes to module setup or configuration. * Includes most capabilities of [nginx 1.31.2](https://nginx.org/en/CHANGES) and a number of [new features](#index-features-oss). We build binary packages for a range of [systems and architectures](https://en.angie.software//angie/docs/installation/index.md#install-packages), as well as [Docker images](https://en.angie.software//angie/docs/installation/docker.md#docker-images). The source code is open in our [public repositories](https://en.angie.software//angie/docs/development.md#development) under a [BSD-like license](https://en.angie.software//angie/license-angie.md#license-angie). Also, a commercial version with [additional features](#index-features-pro) is marketed as Angie PRO. A choice of ready-made Angie packages, Docker images, and source code build options. Startup and run-time control; configuration, modules, directives, and variables. Resolving technical issues with Angie, available feedback routes. Information for developers who want to contribute to the project. ## Current Version **Angie 1.12.1** and **Angie PRO 1.12.1** were released on **July 17, 2026**. New versions appear quarterly; in between, we publish urgent fixes and important updates. See also the complete version history for [Angie](https://en.angie.software//angie/docs/oss_changes.md#oss-changes) and [Angie PRO](https://en.angie.software//angie/docs/pro_changes.md#pro-changes). ## Angie Advantages over nginx Core advantages available in the free open-source version of Angie: **Observability and monitoring** - Exposing basic information about the web server, its [configuration](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#a-api-config-files), as well as [metrics](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#metrics) of proxied servers, client connections, shared memory zones, TLS certificates, and many other things via a RESTful [API](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#a-api) interface in JSON format. - Collecting arbitrary [custom metrics](https://en.angie.software//angie/docs/configuration/custom-metrics.md#custom-metrics-config) for [HTTP](https://en.angie.software//angie/docs/configuration/modules/http/http_metric.md#http-metric) and [stream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_metric.md#stream-metric) traffic in real time with the Metric module, using configurable aggregation methods (counters, histograms, moving averages, and so on); metrics are grouped by arbitrary keys and exposed through the statistics API. - Exporting statistics in [Prometheus](https://en.angie.software//angie/docs/configuration/modules/http/http_prometheus.md#id1) format with [customizable templates](https://en.angie.software//angie/docs/configuration/modules/http/http_prometheus.md#prometheus-template). - Enhanced error logging with the [error_log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log) directive: message filtering with the `filter=` parameter, JSON output with the `format=` parameter, and a configurable logging rate with the `rate=` parameter, plus custom tags via the [error_log_user_tag](https://en.angie.software//angie/docs/configuration/modules/http/index.md#error-log-user-tag) directive. - Monitoring the server through the browser with the [Console Light](https://en.angie.software//angie/docs/configuration/monitoring.md#monitoring) visual monitoring tool. See the online demo: [https://console.angie.software/](https://console.angie.software/) **TLS and security** - The [ACME](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#id1) client in Angie, enabled in our packages and images, so there is no separate module to install: automatic issuance and renewal of TLS certificates with [HTTP, DNS, and TLS-ALPN](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) domain validation. DNS validation opens the way to wildcard certificates, the same automation is available in the `stream` context through the Stream [ACME](https://en.angie.software//angie/docs/configuration/modules/stream/stream_acme.md#stream-acme) module, and the [acme_hook](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-hook) directive lets a custom handler fulfill any of these validation methods. - TLS 1.3 Early Data (0-RTT) support in the `stream` module. - [Server](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-ntls)- and [client-side](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ssl-ntls) support for NTLS when using the [TongSuo](https://github.com/Tongsuo-Project/Tongsuo) TLS library, enabled [at build time](https://en.angie.software//angie/docs/installation/sourcebuild.md#install-source-features). **Proxying and load balancing** - Dynamic updating of upstream groups based on events and labels from [Docker containers](https://en.angie.software//angie/docs/configuration/modules/http/http_docker.md#http-docker) (or similar tools like Podman) without server reload. - Genuine [response-time load balancing](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-least-time): requests go to the server with the lowest measured response time, tracked as an exponentially weighted moving average whose [smoothing factor](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-response-time-factor) is configurable, from inert averaging to a quick reaction to spikes. - Recommissioning upstream servers after a failure smoothly using the `slow_start` option of the [server](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) directive in both HTTP and stream upstreams. - [Session binding](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-sticky) for the protocols of the `stream` module (TCP/UDP): all connections within one session are directed to the same proxied server. - Graceful decommissioning of a proxied server in the `stream` module with the `drain` option of the [server](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) directive: the server stops accepting new connections but keeps serving sessions already bound to it. **Protocols and traffic** - Production-ready [HTTP/3](https://en.angie.software//angie/docs/configuration/modules/http/http_v3.md#http-v3) support for both client and [proxied server](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http-version) connections, with the ability to use different protocol versions (HTTP/1.x, HTTP/2, HTTP/3) independently on each side (nginx's HTTP/3 is limited to the server side and remains experimental, [suffering from degradations](https://en.angie.software//news/articles/http3-ebpf.md) after reloads). - A built-in [DoH server](https://en.angie.software//angie/docs/configuration/modules/http/http_doh.md#http-doh) (DNS over HTTPS, RFC 8484): it accepts DNS queries over HTTP/HTTPS and proxies them to DNS server groups over UDP or TCP. - Passing PROXY Protocol v2 to proxied servers in the `stream` module, with the ability to set arbitrary TLV values via the [proxy_protocol_tlv](https://en.angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-protocol-tlv) directive. - Converting images between formats, including to HEIC and AVIF, with the `convert` parameter of the [image_filter](https://en.angie.software//angie/docs/configuration/modules/http/http_image_filter.md#id1) directive. - Extending authorization and balancing capabilities for the MQTT protocol with the [mqtt_preread](https://en.angie.software//angie/docs/configuration/modules/stream/stream_mqtt_preread.md#s-mqtt-preread) directive under `stream`. - Informing balancing decisions with RDP protocol's session cookies via the [rdp_preread](https://en.angie.software//angie/docs/configuration/modules/stream/stream_rdp_preread.md#s-rdp-preread) directive under `stream`. - Limiting the [MP4 file transfer rate](https://en.angie.software//angie/docs/configuration/modules/http/http_mp4.md#mp4-limit-rate) proportionally to its bitrate, thus reducing the bandwidth load. - Support for the XOAUTH2 and OAUTHBEARER [authentication methods](https://en.angie.software//angie/docs/configuration/modules/mail/mail_smtp.md#m-smtp-auth) in the mail proxy. **Simpler configuration and operations** - Automatic [DNS resolver](https://en.angie.software//angie/docs/configuration/modules/http/index.md#resolver) configuration from `/etc/resolv.conf`: the file is re-read on changes, eliminating the need to specify DNS server addresses manually. - Several matching expressions at once in a single `location` directive: blocks with shared settings can be [combined](https://en.angie.software//angie/docs/configuration/modules/http/index.md#combined-locations). - The [goto](https://en.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#goto) directive in the rewrite module, performing an internal redirect to a named location without modifying the URI, in place of workarounds based on `try_files` or `error_page`. - Flushing the shared memory zone in [proxy_cache_path](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-path) to disk: the cache index contents are preserved between restarts and updates, which eliminates the cache load delay and brings the server online even faster. - The [time_format](https://en.angie.software//angie/docs/configuration/modules/http/index.md#time-format) directive, defining a variable with a custom time format, supporting `strftime()`-like specifiers and `%L` for milliseconds. - Pre-built [binary packages](https://en.angie.software//angie/docs/installation/external-modules/index.md#install-thirdpartymodules) for many popular third-party modules. ## Additional Angie PRO Features Commercial Angie PRO adds the following to the [open-source version](#index-features-oss): **Dynamic configuration and management** - Managing proxied servers through a RESTful dynamic configuration [API](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-config): servers can be put into and taken out of balancing, and their weights and other parameters changed on the fly, without reloading worker processes. The visual monitoring console [Console Light](https://en.angie.software//angie/docs/configuration/monitoring.md#monitoring) can also be used to manage the server in your browser. - Overriding the server signature on error pages and in the `Server` header field with an arbitrary value using the [server_tokens](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server-tokens) directive. **Advanced balancing and fault tolerance** - Balancing by [feedback](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-feedback): peers are selected by a variable value; it is assumed to come from the peers themselves, reporting CPU load or other metrics. - Waiting queue for requests, configured using the [queue](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-queue) directive in the `upstream` block: if no server can be picked for a request on the first attempt, for example during a load spike, it joins the queue instead of being rejected outright. - Proactively checking the state of proxied servers by sending periodic [probing requests](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe): a failing server leaves balancing before a client request reaches it, not after. - The [no_port](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-no-port) directive in an `upstream` block of the `stream` module, unbinding the port from the group's servers: the port is given in the [proxy_pass](https://en.angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-pass) directive, so a single group can serve proxying to different ports without duplicating the server list. - The [backup_switch](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-backup-switch) directive in the `upstream` block: backup servers can continue serving requests when the primary servers become accessible again. **Sessions, connections, and caching** - The [sticky learn](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky) mode with session storage in an external store, which allows joining multiple balancers in a cluster. - Conditional [binding of client connections](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-bind-conn) to the proxied server connection, which also enables proxying NTLM. - The [proxy_bind](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-bind) directive, evaluating variables after each proxied server selection: the outgoing address can depend on the selected server; for example, through the [$upstream_current_addr](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-current-addr) variable. - Cache sharding in the proxy module, which enables distributing it across [different disks](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache) depending on the properties of the response. # https://en.angie.software/angie/docs/installation.md # Installation ## Angie Several installation options are available for the free open-source version: | [Binary packages](https://en.angie.software//angie/docs/installation/oss_packages.md#oss-packages) | Recommended installation method;
we build and publish packages for most Linux distributions
and FreeBSD.

Along with this, we also prepare and release our own builds
for many
[popular third-party modules](https://en.angie.software//angie/docs/installation/external-modules/index.md#install-thirdpartymodules). | |------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [Docker images](https://en.angie.software//angie/docs/installation/docker.md#docker-images) | To run in a container, you can download the Docker image from our registry.
We build images from our own packages based on a wide range of distributions.

The images in the registry contain *all* the modules we build,
including third-party ones;
there is also a minimal image without additional modules. | | [Source build](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) | If the previous options don't suit you for some reason,
you can always create your own build from the source code. | You can suggest new installation methods, modules, and distributions on the [forum](https://forum.angie.support) or on [GitHub](https://github.com/webserver-llc/angie/issues). ## Angie PRO The main installation option for the commercial version is [binary packages](https://en.angie.software//angie/docs/installation/pro_packages.md#pro-packages), stored in a secure private repository; to access it, you need to sign a contract and purchase a license. Builds are available for most POSIX-compatible systems; in addition, we can create and test your build for a specific distribution and installation method. ## Third-Party Modules and Other Sources We prepare and publish builds for many [popular third-party modules](https://en.angie.software//angie/docs/installation/external-modules/index.md#install-thirdpartymodules) in our repository. In addition, for a number of operating systems and distributions, Angie can be installed from their [own repositories](https://en.angie.software//angie/docs/installation/thirdparty.md#thirdparty). # https://en.angie.software/angie/docs/installation/oss_packages.md # Package Installation of Angie To install and update Angie using your distribution's package manager, add and configure the appropriate repository. ## Distributions | Name | Versions | Architectures | |-----------------------------------|--------------------------------|-------------------------------| | [AlmaLinux](#install-yum-oss) | 10, 9, 8 | x86-64, arm64 | | [Alpine](#install-alpine-oss) | 3.23, 3.22, 3.21 | x86-64, arm64 | | [ALT](#install-alt-oss) | 11, 10 8 | x86-64, arm64 x86-64 | | [Astra SE](#install-astrase-oss) | 4.7 1.8, 1.7 | arm64 x86-64 | | [CentOS](#install-yum-oss) | 10, 9 | x86-64, arm64 | | [Debian](#install-deb-oss) | 13, 12, 11 | x86-64, arm64 | | [Fedora](#install-yum-oss) | 44, 43 | x86-64, arm64 | | [FreeBSD](#install-freebsd-oss) | 15, 14 | x86-64, arm64 | | [MSVSphere](#install-yum-oss) | 10, 9 8 | x86-64, arm64 x86-64 | | [openSUSE](#install-opensuse-oss) | 16, 15 | x86-64, arm64 | | [Oracle Linux](#install-yum-oss) | 10, 9, 8 | x86-64, arm64 | | [OSNova](#install-osnova-oss) | 3.3.0, 2.13 | x86-64 | | [RED OS](#install-yum-oss) | 8, 7 | x86-64, arm64 | | [Rocky Linux](#install-yum-oss) | 10, 9, 8 | x86-64, arm64 | | [ROSA](#install-yum-oss) | Chrome 13 Chrome 12 Fresh 12 | x86-64 x86-64, arm64 x86-64 | | [SberLinux](#install-yum-oss) | 9 | x86-64 | | [Ubuntu](#install-deb-oss) | 26.04, 24.04, 22.04 | x86-64, arm64 | ### Test Builds We test and build code from our repository daily, and these [nightly builds](https://download.angie.software/angie-nightly/) are suitable for exploring new features ahead of official releases. The version of the nightly builds always corresponds to the upcoming release. The naming and installation process is generally similar to what's shown below, but instead of the path prefix `https://download.angie.software/angie/*` use `https://download.angie.software/angie-nightly/*`. ### Alma, CentOS, Fedora, MSVSphere, Oracle, RED OS, Rocky, ROSA, SberLinux 1. To add the repo, create a file named `/etc/yum.repos.d/angie.repo` with the following contents: Alma ```ini [angie] name=Angie repo baseurl=https://download.angie.software/angie/almalinux/$releasever/ gpgcheck=1 enabled=1 gpgkey=https://angie.software/keys/angie-signing.gpg.asc ``` CentOS ```ini [angie] name=Angie repo baseurl=https://download.angie.software/angie/centos/$releasever/ gpgcheck=1 enabled=1 gpgkey=https://angie.software/keys/angie-signing.gpg.asc ``` Fedora ```ini [angie] name=Angie repo baseurl=https://download.angie.software/angie/fedora/$releasever/ gpgcheck=1 enabled=1 gpgkey=https://angie.software/keys/angie-signing.gpg.asc ``` MSVSphere ```ini [angie] name=Angie repo baseurl=https://download.angie.software/angie/msvsphere/$releasever/ gpgcheck=1 enabled=1 gpgkey=https://angie.software/keys/angie-signing.gpg.asc ``` Oracle ```ini [angie] name=Angie repo baseurl=https://download.angie.software/angie/oracle/$releasever/ gpgcheck=1 enabled=1 gpgkey=https://angie.software/keys/angie-signing.gpg.asc ``` RED OS ```ini [angie] name=Angie repo baseurl=https://download.angie.software/angie/redos/$releasever/ gpgcheck=1 enabled=1 gpgkey=https://angie.software/keys/angie-signing.gpg.asc ``` Rocky ```ini [angie] name=Angie repo baseurl=https://download.angie.software/angie/rocky/$releasever/ gpgcheck=1 enabled=1 gpgkey=https://angie.software/keys/angie-signing.gpg.asc ``` ROSA Chrome ```ini [angie] name=Angie repo baseurl=https://download.angie.software/angie/rosa-chrome/$releasever/ gpgcheck=1 enabled=1 gpgkey=https://angie.software/keys/angie-signing.gpg.asc priority=9 ``` ROSA Fresh ```ini [angie] name=Angie repo baseurl=https://download.angie.software/angie/rosa/$releasever/ gpgcheck=1 enabled=1 gpgkey=https://angie.software/keys/angie-signing.gpg.asc priority=9 ``` SberLinux ```ini [angie] name=Angie repo baseurl=https://download.angie.software/angie/sberlinux/$releasever/ gpgcheck=1 enabled=1 gpgkey=https://angie.software/keys/angie-signing.gpg.asc priority=9 ``` 2. Install the Angie package: ```console $ sudo yum install -y angie $ # -- OR -- $ sudo dnf install -y angie ``` 3. (*Optional*) Install any [extra](#install-extras-oss) packages you need: ```console $ sudo yum install -y $ # -- OR -- $ sudo dnf install -y ``` 4. Start the service: ```console $ sudo systemctl start angie ``` 5. To autostart Angie after server reboot: ```console $ sudo systemctl enable angie ``` ### Alpine 1. Install the prerequisites for adding the Angie repo: ```console $ sudo apk update $ sudo apk add curl ca-certificates ``` 2. Download the public key of the Angie repo for package verification: ```console $ sudo curl -o /etc/apk/keys/angie-signing.rsa \ https://angie.software/keys/angie-signing.rsa ``` 3. Add the Angie repo: ```console $ echo "https://download.angie.software/angie/alpine/v$(egrep -o \ '[0-9]+\.[0-9]+' /etc/alpine-release)/main" \ | sudo tee -a /etc/apk/repositories > /dev/null ``` 4. Update the repo indexes: ```console $ sudo apk update ``` 5. Install the Angie package: ```console $ sudo apk add angie ``` 6. (*Optional*) Install any [extra](#install-extras-oss) packages you need: ```console $ sudo apk add ``` 7. Start the service: ```console $ sudo service angie start ``` 8. To autostart Angie after server reboot: ```console $ sudo rc-update add angie ``` ### ALT 1. Create the `/etc/ssl/angie/` directory: ```console $ sudo mkdir -p /etc/ssl/angie/ ``` 2. Install the prerequisites for adding the Angie repo: ```console $ sudo apt-get update $ sudo apt-get install -y curl apt-https ``` 3. Download the public key of the Angie repo for package verification: ```console $ sudo curl -o /etc/ssl/angie/angie-signing.gpg \ https://angie.software/keys/angie-signing.gpg ``` 4. Import the downloaded key into the trusted key ring: ```console $ sudo gpg --no-default-keyring \ --keyring /usr/lib/alt-gpgkeys/pubring.gpg --import /etc/ssl/angie/angie-signing.gpg ``` 5. Save the key's signature: ```sh $ echo 'simple-key "angie" { Fingerprint "EB8EAF3D4EF1B1ECF34865A2617AB978CB849A76"; Name "Angie (Signing Key) "; }' | sudo tee /etc/apt/vendors.list.d/angie.list > /dev/null ``` 6. Add the Angie repo: ALT 11 ```console $ echo "rpm [angie] https://download.angie.software/angie/altlinux/11/ $(uname -m) main" \ | sudo tee /etc/apt/sources.list.d/angie.list > /dev/null ``` ALT 10 ```console $ echo "rpm [angie] https://download.angie.software/angie/altlinux/10/ $(uname -m) main" \ | sudo tee /etc/apt/sources.list.d/angie.list > /dev/null ``` ALT SP 10 ```console $ echo "rpm [angie] https://download.angie.software/angie/altlinux-sp/10/ $(uname -m) main" \ | sudo tee /etc/apt/sources.list.d/angie.list > /dev/null ``` ALT SP 8 ```console $ echo "rpm [angie] https://download.angie.software/angie/altlinux-sp/8/ $(uname -m) main" \ | sudo tee /etc/apt/sources.list.d/angie.list > /dev/null ``` 7. Update the repo indexes: ```console $ sudo apt-get update ``` 8. Install the Angie package: ```console $ sudo apt-get install -y angie ``` 9. (*Optional*) Install any [extra](#install-extras-oss) packages you need: ```console $ sudo apt-get install -y ``` 10. Start the service: ```console $ sudo systemctl start angie ``` 11. To autostart Angie after server reboot: ```console $ sudo systemctl enable angie ``` ### Astra SE 1. Install the prerequisites for adding the Angie repo: ```console $ sudo apt-get update $ sudo apt-get install -y ca-certificates curl lsb-release ``` 2. Download the public key of the Angie repo for package verification: ```console $ sudo curl -o /etc/apt/trusted.gpg.d/angie-signing.gpg \ https://angie.software/keys/angie-signing.gpg ``` 3. Add the Angie repo: ```console $ echo "deb https://download.angie.software/angie/astra-se/$(egrep -o \ '[0-9]+.[0-9]+' /etc/astra_version) unstable main" \ | sudo tee /etc/apt/sources.list.d/angie.list > /dev/null ``` 4. Update the repo indexes: ```console $ sudo apt-get update ``` 5. (*Optional*) When running a Closed Software Environment ([CSE](https://wiki.astralinux.ru/pages/viewpage.action?pageId=41190634)), install the key package for Angie binary verification: ```console $ sudo apt-get install -y angie-digsig-key ``` Update the CSE: ```console $ sudo update-initramfs -uk all ``` Then **restart the server**: ```console $ sudo shutdown -r now ``` 6. Install the Angie package: ```console $ sudo apt-get install -y angie ``` 7. (*Optional*) Install any [extra](#install-extras-oss) packages you need: ```console $ sudo apt-get install -y ``` ### Debian, Ubuntu 1. Install the prerequisites for adding the Angie repo: ```console $ sudo apt-get update $ sudo apt-get install -y ca-certificates curl ``` 2. Download the public key of the Angie repo for package verification: ```console $ sudo curl -o /etc/apt/trusted.gpg.d/angie-signing.gpg \ https://angie.software/keys/angie-signing.gpg ``` 3. Add the Angie repo: ```console $ echo "deb https://download.angie.software/angie/$(. /etc/os-release && echo "$ID/$VERSION_ID $VERSION_CODENAME") main" \ | sudo tee /etc/apt/sources.list.d/angie.list > /dev/null ``` 4. Update the repo indexes: ```console $ sudo apt-get update ``` 5. Install the Angie package: ```console $ sudo apt-get install -y angie ``` 6. (*Optional*) Install any [extra](#install-extras-oss) packages you need: ```console $ sudo apt-get install -y ``` ### OSNova 1. Install the prerequisites for adding the Angie repo: ```console $ sudo apt-get update $ sudo apt-get install -y ca-certificates curl ``` 2. Download the public key of the Angie repo for package verification: ```console $ sudo curl -o /etc/apt/trusted.gpg.d/angie-signing.gpg \ https://angie.software/keys/angie-signing.gpg ``` 3. Add the Angie repo: ```console $ echo "deb https://download.angie.software/angie/osnova/$(egrep -o \ '[0-9]*' /etc/osnova_version | head -1) \ $(. /etc/os-release && echo "$VERSION_CODENAME") main" \ | sudo tee /etc/apt/sources.list.d/angie.list > /dev/null ``` 4. Update the repo indexes: ```console $ sudo apt-get update ``` 5. Install the Angie package: ```console $ sudo apt-get install -y angie ``` 6. (*Optional*) Install any [extra](#install-extras-oss) packages you need: ```console $ sudo apt-get install -y ``` ### FreeBSD 1. To add the Angie repo, create the directories: ```console $ sudo mkdir -p /usr/local/etc/pkg/angie/ /usr/local/etc/pkg/repos/ ``` 2. To configure the repo, create a file named `/usr/local/etc/pkg/repos/angie.conf` with the following contents: ```console angie: { url: "https://download.angie.software/angie/freebsd/${VERSION_MAJOR}/${ARCH}", signature_type: "pubkey", pubkey: "/usr/local/etc/pkg/angie/angie-signing.rsa", enabled: yes } ``` 3. Download the public key of the Angie repo for package verification: ```console $ sudo curl -o /usr/local/etc/pkg/angie/angie-signing.rsa \ https://angie.software/keys/angie-signing.rsa ``` 4. Update the repo indexes: ```console $ sudo pkg update ``` 5. Install the Angie package: ```console $ sudo pkg install -r angie -y angie ``` 6. (*Optional*) Install any [extra](#install-extras-oss) packages you need: ```console $ sudo pkg install -r angie -y ``` 7. Start the service: ```console $ sudo service angie start ``` 8. To autostart Angie after server reboot: ```console $ sudo sysrc angie_enable=YES ``` #### NOTE Since the FreeBSD package manager may incorrectly determine the latest version, use the following approach to update already installed packages: ```console $ sudo pkg upgrade `pkg search -r angie angie-[0-9] | sort -Vr | head -1 | awk {'print $1'}` ``` ### openSUSE 1. To add the repo, create a file named `/etc/zypp/repos.d/angie.repo` with the following contents: ```ini [angie] name=Angie repo baseurl=https://download.angie.software/angie/opensuse/$releasever_major/ gpgcheck=1 enabled=1 gpgkey=https://angie.software/keys/angie-signing.gpg.asc ``` 2. Update the repo indexes: ```console $ sudo zypper refresh ``` 3. Install the Angie package: ```console $ sudo zypper install -y angie ``` 4. (*Optional*) Install any [extra](#install-extras-oss) packages you need: ```console $ sudo zypper install -y ``` 5. Start the service: ```console $ sudo systemctl start angie ``` 6. To autostart Angie after server reboot: ```console $ sudo systemctl enable angie ``` ## Extras Besides the packages that provide the basic functionality, we also publish a few extra packages, both our own and built from curated third-party sources. ### Console Light Web Panel Console Light is a lightweight web monitoring panel for Angie, published as `angie-console-light` in our repos. It is installed in the same way as the `angie` package in the steps above; see the configuration steps in [Console Light Web Monitoring Panel](https://en.angie.software//angie/docs/configuration/monitoring.md#monitoring). ### Dynamic Modules To extend the basic functionality of Angie, you can add various dynamic modules. Modules can be [built from source](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) against a corresponding version of Angie, but it is easier to get them as ready-made packages from our repository: | [angie-module-image-filter](https://en.angie.software//angie/docs/configuration/modules/http/http_image_filter.md#http-image-filter) | Adds transformations for JPEG, GIF, PNG, and WebP images. | |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------| | angie-module-njs:
[HTTP JS](https://en.angie.software//angie/docs/configuration/modules/external-modules/http_js.md#http-js),
[Stream JS](https://en.angie.software//angie/docs/configuration/modules/external-modules/stream_js.md#stream-js) | Enables using njs (a JavaScript subset) in Angie configuration
in the `http` and `stream` contexts, respectively. | | [angie-module-perl](https://en.angie.software//angie/docs/configuration/modules/http/http_perl.md#http-perl) | Enables writing `location` and variable handlers in Perl,
and also invoking Perl from SSI. | | [angie-module-wamr](https://en.angie.software//angie/docs/configuration/modules/wasm/wasm_wamr.md#wasm-wamr) | Enables integration with [WebAssembly Micro Runtime](https://github.com/bytecodealliance/wasm-micro-runtime)
for executing WASM code. | | [angie-module-wasm](https://en.angie.software//angie/docs/configuration/modules/wasm/index.md#wasm-core) | Adds core WASM support. | | [angie-module-wasmtime](https://en.angie.software//angie/docs/configuration/modules/wasm/wasm_wasmtime.md#wasm-wasmtime) | Enables integration with the [Wasmtime](https://wasmtime.dev/)
runtime for executing WASM code. | | [angie-module-xslt](https://en.angie.software//angie/docs/configuration/modules/http/http_xslt.md#http-xslt) | Adds a filter to transform XML responses with XSLT stylesheets. | To use an installed module in a [configuration](https://en.angie.software//angie/docs/configuration/configfile.md#configfile), load it using the [load_module](https://en.angie.software//angie/docs/configuration/modules/core.md#load-module) directive in the `main` context: ```nginx load_module modules/.so; ``` A wide range of [third-party modules](https://en.angie.software//angie/docs/installation/external-modules/index.md#install-thirdpartymodules) is also available. # https://en.angie.software/angie/docs/installation/docker.md # Angie Docker Images To run Angie in a [Docker](https://docs.docker.com/engine/reference/commandline/cli/) container, use the images from our registry: `docker.angie.software`. They are built based on our [binary packages](https://en.angie.software//angie/docs/installation/oss_packages.md#oss-packages) and the official base images of several operating systems. #### NOTE These images can also be run with Docker-compatible container engines such as Podman. The recommended Podman version is 4.9.3 or higher. #### NOTE Also note the [Docker](https://en.angie.software//angie/docs/configuration/modules/http/http_docker.md#http-docker) module, which implements dynamic updating of upstream server groups based on Docker container labels. ## Minimal Images - `angie:minimal`: version 1.12.1 based on Alpine 3.22. - `angie:-minimal`: specified version based on Alpine 3.22. These images include only the `angie` package. ## Templated Images - `angie:templated`: version 1.12.1 based on Alpine 3.22. - `angie:-templated`: specified version based on Alpine 3.22. These images set the following environment variables: ```docker ENV ANGIE_BINARY="angie" ENV ANGIE_CONFIG_TEMPLATE="/etc/angie/angie.conf.t" ENV ANGIE_ERROR_LOG_SEVERITY="notice" ENV ANGIE_FEATURE_RELOAD="on" ENV ANGIE_FEATURE_TEMPLATE="on" ENV ANGIE_LOAD_MODULES="" ENV ANGIE_PID_FILE="/run/angie/angie.pid" ENV ANGIE_WORKER_CONNECTIONS="65536" ENV ANGIE_WORKER_RLIMIT_NOFILE="65536" ``` These variables can be used to customize the container behavior: - `ANGIE_BINARY`: Allows running the [debug version](https://en.angie.software//angie/docs/troubleshooting.md#debug-logging). - `ANGIE_ERROR_LOG_SEVERITY`: Sets the severity level for entries in the main [error log](https://en.angie.software//angie/docs/configuration/processing.md#logging) file. - `ANGIE_LOAD_MODULES`: Loads one or more available modules (all modules are included in the image). Specify a comma-separated list of modules without spaces. - `ANGIE_PID_FILE`: Sets an alternative location for the process identifier (PID) file. - `ANGIE_FEATURE_TEMPLATE`: Generates [Angie configuration](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) using the [gomplate](https://docs.gomplate.ca/) tool at container startup. Parameters used: `--input-dir /etc/angie/templates` and `--output-dir /etc/angie`. - `ANGIE_FEATURE_RELOAD`: Enables handling of `SIGHUP`, `SIGQUIT`, and `SIGTERM` signals. These include the following [packages](https://en.angie.software//angie/docs/installation/external-modules/index.md#install-thirdpartymodules) (if they were released for the [Angie version](https://en.angie.software//angie/docs/oss_changes.md#oss-changes) that the image was built with): ### Package List - `angie-console-light` - `angie-module-auth-jwt` - `angie-module-auth-ldap` - `angie-module-auth-pam` - `angie-module-auth-spnego` - `angie-module-auth-totp` - `angie-module-brotli` - `angie-module-cache-purge` - `angie-module-cgi` - `angie-module-combined-upstreams` - `angie-module-dav-ext` - `angie-module-dynamic-limit-req` - `angie-module-echo` - `angie-module-enhanced-memcached` - `angie-module-eval` - `angie-module-geoip2` - `angie-module-headers-more` - `angie-module-http-auth-radius` - `angie-module-image-filter` - `angie-module-keyval` - `angie-module-lua` - `angie-module-modsecurity` - `angie-module-ndk` - `angie-module-njs` - `angie-module-opentracing` - `angie-module-otel` - `angie-module-perl` - `angie-module-postgres` - `angie-module-redis2` - `angie-module-rtmp` - `angie-module-set-misc` - `angie-module-subs` - `angie-module-testcookie` - `angie-module-unbrotli` - `angie-module-upload` - `angie-module-vod` - `angie-module-vts` - `angie-module-wasm` - `angie-module-wasmtime` - `angie-module-xslt` - `angie-module-zip` - `angie-module-zstd` ### Examples The configuration used in templated images applies the variables approximately as follows: ```none ... {{- if has $modules "zstd"}} # package: angie-module-zstd load_module modules/ngx_http_zstd_filter_module.so; load_module modules/ngx_http_zstd_static_module.so; {{end}} user angie; worker_processes auto; worker_rlimit_nofile {{.Env.ANGIE_WORKER_RLIMIT_NOFILE}}; error_log /var/log/angie/error.log {{.Env.ANGIE_ERROR_LOG_SEVERITY}}; pid {{.Env.ANGIE_PID_FILE}}; events { worker_connections {{.Env.ANGIE_WORKER_CONNECTIONS}}; } http { include /etc/angie/mime.types; default_type application/octet-stream; log_format main ... ``` Running a container with shell access: ```console $ docker run -it --pull always --rm --entrypoint=sh \ docker.angie.software/angie:templated ``` Run Angie with custom connection parameters and modules (the command **angie -T** will output the complete configuration): ```console $ docker run -it --rm -e ANGIE_WORKER_CONNECTIONS=4 \ -e ANGIE_LOAD_MODULES="auth-jwt,vod" \ docker.angie.software/angie:templated angie -T ``` Start a container with a specified name and additional modules: ```console $ docker run -it --rm --name angie-test \ -e ANGIE_WORKER_CONNECTIONS=4 \ -e ANGIE_LOAD_MODULES="auth-jwt,vod" \ docker.angie.software/angie:templated ``` Reload the configuration of a running container: ```console $ docker kill -s HUP angie-test ``` ## Images with Extra Modules - `angie:latest`: version 1.12.1 based on Alpine 3.22. - `angie:`, `angie:-alpine`: specified version based on Alpine 3.22. - `angie:-debian`: specified version based on Debian 13. - `angie:-rocky`: specified version based on Rocky Linux 9. - `angie:-ubuntu`: specified version based on Ubuntu 24.04 LTS. These include the following [packages](https://en.angie.software//angie/docs/installation/external-modules/index.md#install-thirdpartymodules) (if they were released for the [Angie version](https://en.angie.software//angie/docs/oss_changes.md#oss-changes) that the image was built with): ### Package List - `angie-console-light` - `angie-module-auth-jwt` - `angie-module-auth-ldap` - `angie-module-auth-pam` - `angie-module-auth-spnego` - `angie-module-auth-totp` - `angie-module-brotli` - `angie-module-cache-purge` - `angie-module-cgi` - `angie-module-combined-upstreams` - `angie-module-dav-ext` - `angie-module-dynamic-limit-req` - `angie-module-echo` - `angie-module-enhanced-memcached` - `angie-module-eval` - `angie-module-geoip2` - `angie-module-headers-more` - `angie-module-http-auth-radius` - `angie-module-image-filter` - `angie-module-keyval` - `angie-module-lua` - `angie-module-modsecurity` - `angie-module-ndk` - `angie-module-njs` - `angie-module-opentracing` - `angie-module-otel` - `angie-module-perl` - `angie-module-postgres` - `angie-module-redis2` - `angie-module-rtmp` - `angie-module-set-misc` - `angie-module-subs` - `angie-module-testcookie` - `angie-module-unbrotli` - `angie-module-upload` - `angie-module-vod` - `angie-module-vts` - `angie-module-wasm` - `angie-module-wasmtime` - `angie-module-xslt` - `angie-module-zip` - `angie-module-zstd` ## Running To start a container with Angie on port 8080, providing read-only access to the static files directory `/var/www/` and the configuration file `angie.conf` located in the current working directory: ```console $ docker run --rm --name angie -v /var/www:/usr/share/angie/html:ro \ -v $(pwd)/angie.conf:/etc/angie/angie.conf:ro -p 8080:80 -d docker.angie.software/angie:latest $ curl -I localhost:8080 HTTP/1.1 200 OK Server: Angie/1.12.1 Date: Fri, 17 Jul 2026 10:42:54 GMT Content-Type: text/html Content-Length: 543 Last-Modified: Fri, 17 Jul 2026 09:12:23 GMT Connection: keep-alive ETag: "64c3ccc7-21f" Accept-Ranges: bytes ``` Such configurations are suitable for local development and configuration. When using the [ACME module](https://en.angie.software//angie/docs/configuration/acme.md#acme-config) to obtain certificates, mount the certificate storage directory on a persistent volume so that issued certificates survive container recreation. Otherwise, every recreated container starts with empty storage and requests new certificates, which may hit the CA's [rate limits](https://letsencrypt.org/docs/rate-limits/): ```console $ docker run --rm --name angie -v angie-acme:/var/lib/angie/acme \ -v $(pwd)/angie.conf:/etc/angie/angie.conf:ro -p 80:80 -p 443:443 -d docker.angie.software/angie:latest ``` ## Building Custom Images You can also build your own image based on a supported distribution, adding the Angie layer from [packages](https://en.angie.software//angie/docs/installation/oss_packages.md#oss-packages) or [source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild). Examples of corresponding `Dockerfile` files: ```dockerfile FROM debian:13 LABEL org.opencontainers.image.authors="Release Engineering Team " ARG DEBIAN_FRONTEND=noninteractive RUN set -x \ && apt-get update \ && apt-get install --no-install-recommends --no-install-suggests -y \ ca-certificates curl \ && curl -o /etc/apt/trusted.gpg.d/angie-signing.gpg \ https://angie.software/keys/angie-signing.gpg \ && echo "deb https://download.angie.software/angie/$(. /etc/os-release && echo "$ID/$VERSION_ID $VERSION_CODENAME") main" \ > /etc/apt/sources.list.d/angie.list \ && apt-get update \ && apt-get install --no-install-recommends --no-install-suggests -y \ angie angie-module-geoip2 angie-module-njs \ && rm -Rf /var/lib/apt/lists \ /etc/apt/sources.list.d/angie.list \ /etc/apt/trusted.gpg.d/angie-signing.gpg \ && ln -sf /dev/stdout /var/log/angie/access.log \ && ln -sf /dev/stderr /var/log/angie/error.log EXPOSE 80 CMD ["angie", "-g", "daemon off;"] ``` ```dockerfile FROM alpine:3.22 LABEL org.opencontainers.image.authors="Release Engineering Team " RUN set -x \ && apk add --no-cache ca-certificates curl \ && curl -o /etc/apk/keys/angie-signing.rsa https://angie.software/keys/angie-signing.rsa \ && echo "https://download.angie.software/angie/alpine/v$(egrep -o \ '[0-9]+\.[0-9]+' /etc/alpine-release)/main" >> /etc/apk/repositories \ && apk add --no-cache angie angie-module-geoip2 angie-module-njs \ && rm /etc/apk/keys/angie-signing.rsa \ && ln -sf /dev/stdout /var/log/angie/access.log \ && ln -sf /dev/stderr /var/log/angie/error.log EXPOSE 80 CMD ["angie", "-g", "daemon off;"] ``` To build a `myangie` image in the directory with such a `Dockerfile` and start a container as shown above: ```console $ docker build -t myangie . $ docker run --rm --name myangie -v /var/www:/usr/share/angie/html:ro \ -v $(pwd)/angie.conf:/etc/angie/angie.conf:ro -p 8080:80 -d myangie ``` # https://en.angie.software/angie/docs/installation/sourcebuild.md # Building Angie from Source We recommend installing Angie from official pre-built [packages](https://en.angie.software//angie/docs/installation/oss_packages.md#oss-packages). However, if you still need your own build, make sure the prerequisites are in place first. #### NOTE Building Angie requires a C compiler (**gcc** or **clang**) and **make**, plus the PCRE2, zlib, and OpenSSL libraries. Install the development packages provided by your distribution. On Debian and Ubuntu: ```console $ sudo apt install build-essential libpcre2-dev zlib1g-dev libssl-dev ``` On RHEL, Fedora, and derivatives: ```console $ sudo dnf install gcc make pcre2-devel zlib-devel openssl-devel ``` Alternatively, build these libraries statically together with Angie using the `--with-pcre=`, `--with-zlib=`, and `--with-openssl=` options shown in the [Examples](#examples-2). To build Angie from source: 1. Download the `.tar.gz` archive from [our website](https://download.angie.software/files/): ```console $ curl -O https://download.angie.software/files/angie-1.12.1.tar.gz ``` 2. Unpack the archive and navigate to the source directory: ```console $ tar -xpf angie-1.12.1.tar.gz $ cd angie-1.12.1 ``` 3. To prepare the build, use the **./configure** script, which determines the specific characteristics of the OS where the build occurs, particularly the methods that Angie can use to handle connections. After a successful run, the script creates a `Makefile`. With the prerequisites installed, a minimal build needs no options: ```console $ ./configure ``` Otherwise, review and set the required [build options](#configure) for the modules and libraries you need (see the [Examples](#examples-2)): ```console $ ./configure ``` 4. When the `Makefile` is ready, build and install Angie: ```console $ make $ make install ``` ## Default Builds and Official Packages Without options, **./configure** prepares a minimal build: an HTTP server with only the modules that are enabled by default. These include Angie's own [API](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#http-api), [Metric](https://en.angie.software//angie/docs/configuration/modules/http/http_metric.md#http-metric), [Prometheus](https://en.angie.software//angie/docs/configuration/modules/http/http_prometheus.md#http-prometheus), [DoH](https://en.angie.software//angie/docs/configuration/modules/http/http_doh.md#http-doh), and [Docker](https://en.angie.software//angie/docs/configuration/modules/http/http_docker.md#http-docker) modules, the proxying modules, and the standard load-balancing methods. The full default set is exactly what the tables in [Enabling and Disabling Modules](#enabling-and-disabling-modules) list with `--without-` options; everything listed there with a `--with-` option stays out unless you enable it. Official Angie [packages](https://en.angie.software//angie/docs/installation/oss_packages.md#oss-packages) and Docker images add the following optional modules and features on top of these defaults: - HTTP: [SSL](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#http-ssl) with [HTTP/2](https://en.angie.software//angie/docs/configuration/modules/http/http_v2.md#http-v2) and [HTTP/3](https://en.angie.software//angie/docs/configuration/modules/http/http_v3.md#http-v3), [ACME](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme), [Addition](https://en.angie.software//angie/docs/configuration/modules/http/http_addition.md#http-addition), [Auth Request](https://en.angie.software//angie/docs/configuration/modules/http/http_auth_request.md#http-auth-request), [DAV](https://en.angie.software//angie/docs/configuration/modules/http/http_dav.md#http-dav), [FLV](https://en.angie.software//angie/docs/configuration/modules/http/http_flv.md#http-flv), [GunZIP](https://en.angie.software//angie/docs/configuration/modules/http/http_gunzip.md#http-gunzip), [Gzip Static](https://en.angie.software//angie/docs/configuration/modules/http/http_gzip_static.md#http-gzip-static), [MP4](https://en.angie.software//angie/docs/configuration/modules/http/http_mp4.md#http-mp4), [Random Index](https://en.angie.software//angie/docs/configuration/modules/http/http_random_index.md#http-random-index), [RealIP](https://en.angie.software//angie/docs/configuration/modules/http/http_realip.md#http-realip), [Secure Link](https://en.angie.software//angie/docs/configuration/modules/http/http_secure_link.md#http-secure-link), [Slice](https://en.angie.software//angie/docs/configuration/modules/http/http_slice.md#http-slice), [Stub Status](https://en.angie.software//angie/docs/configuration/modules/http/http_stub_status.md#http-stub-status), and [Sub](https://en.angie.software//angie/docs/configuration/modules/http/http_sub.md#http-sub) - the [Stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) server with [ACME](https://en.angie.software//angie/docs/configuration/modules/stream/stream_acme.md#stream-acme), [MQTT Preread](https://en.angie.software//angie/docs/configuration/modules/stream/stream_mqtt_preread.md#stream-mqtt-preread), [RDP Preread](https://en.angie.software//angie/docs/configuration/modules/stream/stream_rdp_preread.md#stream-rdp-preread), [RealIP](https://en.angie.software//angie/docs/configuration/modules/stream/stream_realip.md#stream-realip), [SSL](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#stream-ssl), and [SSL Preread](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl_preread.md#stream-ssl-preread) - the [Mail](https://en.angie.software//angie/docs/configuration/modules/mail/index.md#mail-core) server with [SSL](https://en.angie.software//angie/docs/configuration/modules/mail/mail_ssl.md#mail-ssl) - [thread pools](https://en.angie.software//angie/docs/configuration/modules/core.md#thread-pool) and asynchronous [file I/O](https://en.angie.software//angie/docs/configuration/modules/http/index.md#aio) A custom build that replaces a packaged one thus usually needs the matching `--with-` options from this list; each module's reference page also states whether our packages include it. Angie PRO [packages](https://en.angie.software//angie/docs/installation/pro_packages.md#pro-packages) are built with the same set of optional modules and additionally include active [health probes](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#http-upstream-probe) and [feedback](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-feedback)-based balancing for both HTTP and stream upstreams, plus HTTP request [queues](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-queue). Modules with heavy external dependencies, such as [XSLT](https://en.angie.software//angie/docs/configuration/modules/http/http_xslt.md#http-xslt), [Image Filter](https://en.angie.software//angie/docs/configuration/modules/http/http_image_filter.md#http-image-filter), [Perl](https://en.angie.software//angie/docs/configuration/modules/http/http_perl.md#http-perl), [njs](https://en.angie.software//angie/docs/configuration/modules/external-modules/http_js.md#http-js), and the [WebAssembly](https://en.angie.software//angie/docs/configuration/modules/wasm/index.md#wasm-core) family, aren't compiled into official builds; we ship them as separate dynamic module packages, listed for [Angie](https://en.angie.software//angie/docs/installation/oss_packages.md#install-dynamicmodules-oss) and [Angie PRO](https://en.angie.software//angie/docs/installation/pro_packages.md#install-dynamicmodules-pro). We also package a curated set of [third-party modules](https://en.angie.software//angie/docs/installation/external-modules/index.md#install-thirdpartymodules); check it before building a third-party module yourself. To see how an installed Angie was built, run `angie -V`; it prints the exact **./configure** options of that build. `angie -M` lists its modules, both built-in and loaded. Both options are described among the [command-line options](https://en.angie.software//angie/docs/configuration/runtime.md#runtime-cli-options). ## Build Options ### General | Option | Description | Default | |------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------| | `--help` | Prints a help message. | | | `--user=`name | Sets the name of an unprivileged user whose credentials will be used by
worker processes. After installation, the name can always be changed in
the `angie.conf` configuration file using the [user](https://en.angie.software//angie/docs/configuration/modules/core.md#user)
directive. | `nobody` | | `--group=`name | Sets the name of a group whose credentials will be used by
worker processes. After installation, the name can always be changed in
the `angie.conf` configuration file using the [user](https://en.angie.software//angie/docs/configuration/modules/core.md#user)
directive. | `--user` setting | | `--build=`name | Sets an optional name for the build. | | | `--builddir=`path | Sets the build directory. | `objs` | | `--feature-cache=`path | Specifies the directory for caching build artifacts. | If set without a path, `--builddir` setting is used | ### Paths | Option | Description | Default | |-------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------| | `--prefix=`path | Defines the directory that will store server files. This same directory
will also be used for all relative paths set by **./configure**
(except for paths to library sources) and in the `angie.conf`
configuration file. | `/usr/local/angie` | | `--sbin-path=`path | Sets the name of the Angie executable. This name is used only during
installation. | `/sbin/angie` | | `--modules-path=`path | Defines the directory where dynamic modules will be installed. | `/modules` | | `--conf-path=`path | Sets the name of the `angie.conf` [configuration file](https://en.angie.software//angie/docs/configuration/configfile.md#configfile). If needed, you can always start Angie with a different
configuration file using the `-c` [command-line option](https://en.angie.software//angie/docs/configuration/runtime.md#runtime-cli-options). | `/conf/angie.conf` | | `--error-log-path=`path | Sets the name of the primary error, warning, and diagnostic log file.
After installation, the file name can always be changed in the
`angie.conf` configuration file using the [error_log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log)
directive. | `/logs/error.log` | | `--pid-path=`path | Sets the name of the `angie.pid` file that will store the process
ID of the main process. After installation, the file name can always be
changed in the `angie.conf` configuration file using the [pid](https://en.angie.software//angie/docs/configuration/modules/core.md#pid)
directive. | `/logs/angie.pid` | | `--lock-path=`path | Sets the prefix for lock file names. After installation,
the value can always be changed in the `angie.conf` configuration
file using the [lock_file](https://en.angie.software//angie/docs/configuration/modules/core.md#lock-file) directive. | `/logs/angie.lock` | | `--http-acme-client-path=`path | Sets the directory to store certificates and keys for
`server` blocks that have [acme](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#id1) directives defined. | `/acme_client` | | `--http-log-path=`path | Sets the name of the primary request log file for the HTTP server. After
installation, the file name can always be changed in the
`angie.conf` configuration file using the [access_log](https://en.angie.software//angie/docs/configuration/modules/http/http_log.md#access-log)
directive. | `/logs/access.log` | | `--http-client-body-temp-path=`path | Defines the directory for storing temporary files that hold client request
bodies. After installation, the directory can always be changed in the
`angie.conf` configuration file using the
[client_body_temp_path](https://en.angie.software//angie/docs/configuration/modules/http/index.md#client-body-temp-path) directive. | `/client_body_temp` | | `--http-proxy-temp-path=`path | Defines the directory for storing temporary files with data received from
proxied servers. After installation, the directory can always be changed
in the `angie.conf` configuration file using the
[proxy_temp_path](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-temp-path) directive. | `/proxy_temp` | | `--http-fastcgi-temp-path=`path | Defines the directory for storing temporary files with data received from
FastCGI servers. After installation, the directory can always be changed
in the `angie.conf` configuration file using the
[fastcgi_temp_path](https://en.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-temp-path) directive. | `/fastcgi_temp` | | `--http-uwsgi-temp-path=`path | Defines the directory for storing temporary files with data received from
uWSGI servers. After installation, the directory can always be changed in
the `angie.conf` configuration file using the
[uwsgi_temp_path](https://en.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-temp-path) directive. | `/uwsgi_temp` | | `--http-scgi-temp-path=`path | Defines the directory for storing temporary files with data received from
SCGI servers. After installation, the directory can always be changed in
the `angie.conf` configuration file using the
[scgi_temp_path](https://en.angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-temp-path) directive. | `/scgi_temp` | ### Features and dependencies | `--with-select_module`, `--without-select_module` | Enables or disables building a module that allows the server to work with
the `select()` method. This module is built automatically if the
platform does not appear to support more appropriate methods such as
`kqueue`, `epoll`, or `/dev/poll`. | |-----------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `--with-poll_module`, `--without-poll_module` | Enables or disables building a module that allows the server to work with
the `poll()` method. This module is built automatically if the
platform does not appear to support more appropriate methods such as
`kqueue`, `epoll`, or `/dev/poll`. | | `--with-threads` | Enables the use of [thread pools](https://en.angie.software//angie/docs/configuration/modules/core.md#thread-pool)
(`aio threads` mode). | | `--with-file-aio` | Enables the use of [asynchronous file I/O](https://en.angie.software//angie/docs/configuration/modules/http/index.md#aio) (AIO) on FreeBSD
and Linux (`aio on` mode). | | `--with-debug` | Enables the [debugging log](https://en.angie.software//angie/docs/troubleshooting.md#debug-logging). | | `--without-http-cache` | Disables the HTTP cache. | | `--with-pcre`, `--with-pcre=`path | Enables the use of the PCRE library.

The optional parameter sets the path to the sources of the PCRE library.
The library distribution needs to be downloaded from the [PCRE](http://www.pcre.org/) site and extracted. The rest is done by Angie's
**./configure** and **make** commands.

The library is **required** for regular expression support in the
`location` directive and for the [Rewrite](https://en.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#http-rewrite) module. | | `--with-pcre-opt=`parameters | Sets additional build parameters for PCRE. | | `--with-pcre-jit` | Builds the PCRE library with JIT compilation support (the [pcre_jit](https://en.angie.software//angie/docs/configuration/modules/core.md#pcre-jit)
directive). | | `--without-pcre` | Disables the use of the PCRE library. | | `--without-pcre2` | Disables the use of the PCRE2 library instead of the original PCRE library. | | `--with-libatomic`, `--with-libatomic=`path | Enables building with the **libatomic_ops** library.
The optional parameter sets the path to the library sources. | | `--with-openssl=`path | Enables static building and sets the path to the OpenSSL library sources. AWS-LC can be used as an OpenSSL-compatible library. | | `--with-openssl-opt=`parameters | Sets additional build parameters for OpenSSL. | | `--with-ntls` | Enables NTLS support in the HTTP module ([server-side](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-ntls), [client-side](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ssl-ntls)) and stream
module ([server-side](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#s-ssl-ntls), [client-side](https://en.angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-ssl-ntls)) when building with an SSL library that supports NTLS. | | `--with-zlib=`path | Sets the path to the sources of the zlib library. The library
distribution (version 1.1.3 or later) needs to be downloaded from the
[zlib site](https://zlib.net/) and extracted; releases older than the
current one are archived under [zlib fossils](https://zlib.net/fossils/). The rest is done by Angie's
**./configure** and **make** commands.

The library is **required** for the [GZip](https://en.angie.software//angie/docs/configuration/modules/http/http_gzip.md#http-gzip) module. | | `--with-zlib-opt=`parameters | Sets additional build parameters for zlib. | | `--with-zlib-asm=`cpu | Enables the use of assembly optimizations for building zlib,
optimized for one of the following processors: `pentium`,
`pentiumpro`. | ### Enabling and Disabling Modules You can disable modules that are enabled by default, or enable modules that are available but disabled by default. The `--with-` and `--without-` tables below reflect the defaults of a bare **./configure** run; the exact set that official packages enable is listed in [Default Builds and Official Packages](#install-source-defaults). #### HTTP Enabling additional modules: | `--with-http_acme_module` | Enables building the [ACME](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme) module,
which enables the ACME protocol. | |----------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `--with-http_addition_module` | Enables building the [Addition](https://en.angie.software//angie/docs/configuration/modules/http/http_addition.md#http-addition) module that allows adding text
before and after a response. | | `--with-http_auth_request_module` | Enables building the [Auth Request](https://en.angie.software//angie/docs/configuration/modules/http/http_auth_request.md#http-auth-request) module that provides
client authorization capability based on the result of a subrequest. | | `--with-http_dav_module` | Enables building the [DAV](https://en.angie.software//angie/docs/configuration/modules/http/http_dav.md#http-dav) module
intended for automating file management tasks on the server via the
WebDAV protocol. | | `--with-http_degradation_module` | Enables building the Degradation module that allows returning HTTP status
codes 204 or 444 for certain `location` blocks.

This module can only be used in cases where `sbrk(0)`
shows the actual amount of memory allocated to the process. In other
words, the module works on FreeBSD up to version 7.0 by default. Starting
from version 7.0, it works only if `MALLOC_OPTIONS=Dm` is set. On
Linux it does not work. | | `--with-http_flv_module` | Enables building the [FLV](https://en.angie.software//angie/docs/configuration/modules/http/http_flv.md#http-flv) module
that provides server-side pseudo-streaming support for Flash
Video (FLV) files. | | `--with-http_geoip_module`, `--with-http_geoip_module=dynamic` | Enables building the [GeoIP](https://en.angie.software//angie/docs/configuration/modules/http/http_geoip.md#http-geoip) module that creates variables whose
values are determined based on the client's IP address and ready-made
[MaxMind](http://www.maxmind.com/) databases. | | `--with-http_gunzip_module` | Enables building the [GunZIP](https://en.angie.software//angie/docs/configuration/modules/http/http_gunzip.md#http-gunzip) module that allows decompressing
responses with `Content-Encoding: gzip` for clients that do not
support the `gzip` compression method. | | `--with-http_gzip_static_module` | Enables building the [GZip Static](https://en.angie.software//angie/docs/configuration/modules/http/http_gzip_static.md#http-gzip-static) module that allows serving
a precompressed file with the same name and the `.gz` extension
instead of a regular file. | | `--with-http_image_filter_module`,
`--with-http_image_filter_module=dynamic` | Enables building the [Image Filter](https://en.angie.software//angie/docs/configuration/modules/http/http_image_filter.md#http-image-filter) module that allows
transforming images in JPEG, GIF, PNG, and WebP formats. | | `--with-http_mp4_module` | Enables building the [MP4](https://en.angie.software//angie/docs/configuration/modules/http/http_mp4.md#http-mp4) module
that provides server-side pseudo-streaming support for MP4 format files. | | `--with-http_perl_module`, `--with-http_perl_module=dynamic` | Enables building the [Perl](https://en.angie.software//angie/docs/configuration/modules/http/http_perl.md#http-perl) module. | | `--with-perl_modules_path=`path | Sets the directory where Perl module files will be located. | | `--with-perl=`path | Sets the name of the Perl executable file. | | `--with-http_random_index_module` | Enables building the [Random Index](https://en.angie.software//angie/docs/configuration/modules/http/http_random_index.md#http-random-index) module that serves requests
ending with a slash (`/`) and returns a random file as the
directory's index file. | | `--with-http_realip_module` | Enables building the [RealIP](https://en.angie.software//angie/docs/configuration/modules/http/http_realip.md#http-realip) module that allows changing the
client address to the one passed in the specified header field. | | `--with-http_secure_link_module` | Enables building the [Secure Link](https://en.angie.software//angie/docs/configuration/modules/http/http_secure_link.md#http-secure-link) module. | | `--with-http_slice_module` | Enables building the [Slice](https://en.angie.software//angie/docs/configuration/modules/http/http_slice.md#http-slice) module that allows splitting a request into
subrequests, each returning a specific range of the response.
The module provides efficient caching of large responses. | | `--with-http_ssl_module` | Enables [SSL](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#http-ssl) support for the
HTTP server.

The OpenSSL library is **required** for this module. | | `--with-http_stub_status_module` | Enables building the [Stub Status](https://en.angie.software//angie/docs/configuration/modules/http/http_stub_status.md#http-stub-status) module that provides access to
basic server status information. | | `--with-http_sub_module` | Enables building the [Sub](https://en.angie.software//angie/docs/configuration/modules/http/http_sub.md#http-sub) module
that allows modifying one specified string in the response to another. | | `--with-http_v2_module` | Enables the [HTTP/2](https://en.angie.software//angie/docs/configuration/modules/http/http_v2.md#http-v2) module. | | `--with-http_v3_module` | Enables the [HTTP/3](https://en.angie.software//angie/docs/configuration/modules/http/http_v3.md#http-v3) module. | #### NOTE For building, it is **strongly recommended** to use an SSL library that supports the [QUIC](https://www.rfc-editor.org/rfc/rfc9000.html) protocol: BoringSSL Building with [BoringSSL](https://boringssl.googlesource.com/boringssl): ```console $ ./configure \ --with-debug \ --with-http_v3_module \ --with-cc-opt="-I../boringssl/include" \ --with-ld-opt="-L../boringssl/build/ssl -L../boringssl/build/crypto" ``` LibreSSL Building with [LibreSSL](https://www.libressl.org/): ```console $ ./configure \ --with-debug \ --with-http_v3_module \ --with-cc-opt="-I../libressl/build/include" \ --with-ld-opt="-L../libressl/build/lib" ``` QuicTLS Building with [QuicTLS](https://github.com/quictls/openssl): ```console $ ./configure \ --with-debug \ --with-http_v3_module \ --with-cc-opt="-I../quictls/build/include" \ --with-ld-opt="-L../quictls/build/lib" ``` Without this, the [OpenSSL](https://openssl.org/) library will be used in compatibility mode, where [early data](https://datatracker.ietf.org/doc/html/rfc8446#section-2.3) sending is not supported and other features are missing, such as session reuse. Such a build will be able to interact **only** with clients and servers using OpenSSL in the same mode. This fallback is silent: if the configured SSL library is missing or unusable, **./configure** uses the system OpenSSL instead of reporting an error. After it finishes, check the `Configuration summary`: a line reading `+ using system OpenSSL library` means the intended QUIC-capable library was not picked up. | `--with-http_xslt_module`, `--with-http_xslt_module=dynamic` | Enables building the [XSLT](https://en.angie.software//angie/docs/configuration/modules/http/http_xslt.md#http-xslt) module that allows transforming
XML responses using XSLT stylesheets.

The **libxml2** and **libxslt** libraries are **required**
for this module. | |----------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `--with-google_perftools_module` | Enables building the [Google PerfTools](https://en.angie.software//angie/docs/configuration/modules/google_perftools.md#google-perftools) module that provides support
for profiling Angie worker processes using [Google Performance
Tools](https://github.com/gperftools/gperftools). The module is intended
for Angie developers. | Disabling standard modules: | `--without-http` | Disables the [HTTP](https://en.angie.software//angie/docs/configuration/modules/http/index.md#http-core) server. | |---------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `--without-http_access_module` | Disables building the [Access](https://en.angie.software//angie/docs/configuration/modules/http/http_access.md#http-access) module
that allows limiting access to certain client addresses. | | `--without-http_api_module` | Disables building the [API](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#http-api) module that
provides a RESTful HTTP interface for accessing JSON-based information
about the web server instance. | | `--without-http_metric_module` | Disables building the [Metric](https://en.angie.software//angie/docs/configuration/modules/http/http_metric.md#http-metric) module. | | `--without-http_auth_basic_module` | Disables building the [Auth Basic](https://en.angie.software//angie/docs/configuration/modules/http/http_auth_basic.md#http-auth-basic)
module that allows limiting access to resources by validating the user
name and password using the HTTP Basic Authentication protocol. | | `--without-http_autoindex_module` | Disables building the [AutoIndex](https://en.angie.software//angie/docs/configuration/modules/http/http_autoindex.md#http-autoindex)
module that processes requests ending with the slash character
(`/`) and produces a directory listing in case the [Index](https://en.angie.software//angie/docs/configuration/modules/http/http_index.md#http-index) module cannot find an index file. | | `--without-http_browser_module` | Disables building the [Browser](https://en.angie.software//angie/docs/configuration/modules/http/http_browser.md#http-browser)
module that creates variables whose values depend on the value of the
`User-Agent` request header field. | | `--without-http_charset_module` | Disables building the [Charset](https://en.angie.software//angie/docs/configuration/modules/http/http_charset.md#http-charset)
module that adds the specified charset to the `Content-Type`
response header field and can additionally convert data from one charset
to another. | | `--without-http_doh_module` | Disables building the [DoH](https://en.angie.software//angie/docs/configuration/modules/http/http_doh.md#http-doh)
module that implements a DNS over HTTPS server. | | `--without-http_empty_gif_module` | Disables building the [Empty GIF](https://en.angie.software//angie/docs/configuration/modules/http/http_empty_gif.md#http-empty-gif) module
that emits a single-pixel transparent GIF. | | `--without-http_fastcgi_module` | Disables building the [FastCGI](https://en.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#http-fastcgi)
module that passes requests to a FastCGI server. | | `--without-http_geo_module` | Disables building the [Geo](https://en.angie.software//angie/docs/configuration/modules/http/http_geo.md#http-geo) module that
creates variables with values depending on the client IP address. | | `--without-http_gzip_module` | Disables building the [GZip](https://en.angie.software//angie/docs/configuration/modules/http/http_gzip.md#http-gzip) module that
compresses the HTTP server responses.

The zlib library is **required** for this module. | | `--without-http_grpc_module` | Disables building the [gRPC](https://en.angie.software//angie/docs/configuration/modules/http/http_grpc.md#http-grpc) module that
passes requests to a gRPC server. | | `--without-http_limit_conn_module` | Disables building the [Limit Conn](https://en.angie.software//angie/docs/configuration/modules/http/http_limit_conn.md#http-limit-conn)
module that limits the number of connections per key, for example, the
number of connections from a single IP address. | | `--without-http_limit_req_module` | Disables building the [Limit Req](https://en.angie.software//angie/docs/configuration/modules/http/http_limit_req.md#http-limit-req)
module that limits the request processing rate per key, for example, the
processing rate of requests coming from a single IP address. | | `--without-http_map_module` | Disables building the [Map](https://en.angie.software//angie/docs/configuration/modules/http/http_map.md#http-map) module that
creates variables with values depending on the values of other variables. | | `--without-http_memcached_module` | Disables building the [Memcached](https://en.angie.software//angie/docs/configuration/modules/http/http_memcached.md#http-memcached)
module that obtains responses from a memcached server. | | `--without-http_mirror_module` | Disables building the [Mirror](https://en.angie.software//angie/docs/configuration/modules/http/http_mirror.md#http-mirror) module
that implements mirroring of an original request by creating background
mirror subrequests. | | `--without-http_prometheus_module` | Disables building the [Prometheus](https://en.angie.software//angie/docs/configuration/modules/http/http_prometheus.md#http-prometheus)
module for the HTTP server. | | `--without-http_proxy_module` | Disables building the [Proxy](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy) module for the HTTP server. | | `--without-http_referer_module` | Disables building the [Referer](https://en.angie.software//angie/docs/configuration/modules/http/http_referer.md#http-referer)
module that can block access to a site for requests with invalid values
in the `Referer` header field. | | `--without-http_rewrite_module` | Disables building the [Rewrite](https://en.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#http-rewrite)
module that allows the HTTP server to redirect requests and change their
URIs.

The PCRE library is **required** for this module. | | `--without-http_scgi_module` | Disables building the [SCGI](https://en.angie.software//angie/docs/configuration/modules/http/http_scgi.md#http-scgi) module that
passes requests to an SCGI server. | | `--without-http_split_clients_module` | Disables building the [Split Clients](https://en.angie.software//angie/docs/configuration/modules/http/http_split_clients.md#http-split-clients) module that creates
variables for A/B testing. | | `--without-http_ssi_module` | Disables building the [SSI](https://en.angie.software//angie/docs/configuration/modules/http/http_ssi.md#http-ssi) module that
processes SSI (Server Side Includes) commands in responses passing
through it. | | `--without-http_upstream_hash_module` | Disables building the module that implements the [hash](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-hash) load
balancing method. | | `--without-http_upstream_ip_hash_module` | Disables building the module that implements the [ip_hash](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-ip-hash) load
balancing method. | | `--without-http_upstream_keepalive_module` | Disables building the module that provides [connection caching](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive) to upstream servers. | | `--without-http_upstream_least_conn_module` | Disables building the module that implements the [least_conn](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-least-conn)
load balancing method. | | `--without-http_upstream_least_time_module` | Disables building the module that implements the [least_time](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-least-time)
load balancing method. | | `--without-http_upstream_random_module` | Disables building the module that implements the [random](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-random) load
balancing method. | | `--without-http_upstream_sticky_module` | Disables building the module that implements [session persistence](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky), ensuring all requests in the client session are passed to
the same server in the upstream. | | `--without-http_upstream_zone_module` | Disables building the module that allows storing the run-time state of an upstream
in a [shared memory zone](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone). | | `--without-http_userid_module` | Disables building the [UserID](https://en.angie.software//angie/docs/configuration/modules/http/http_userid.md#http-userid) module
that sets cookies suitable for client identification. | | `--without-http_uwsgi_module` | Disables building the [uWSGI](https://en.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#http-uwsgi) module
that passes requests to a uWSGI server. | #### Stream modules Enabling additional modules: #### \* - `--with-stream`, `--with-stream=dynamic`
- Enables the core [Stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#stream-core)
module for generic TCP/UDP proxying and load balancing. | `--with-stream_acme_module` | Enables building the [ACME](https://en.angie.software//angie/docs/configuration/modules/stream/stream_acme.md#stream-acme) module,
which enables the ACME protocol. | |--------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `--with-stream_geoip_module`, `--with-stream_geoip_module=dynamic` | Enables the [GeoIP](https://en.angie.software//angie/docs/configuration/modules/stream/stream_geoip.md#stream-geoip) module
that creates variables depending on the client IP address and the
precompiled [MaxMind](http://www.maxmind.com/) databases. | | `--with-stream_mqtt_preread_module` | Enables the [MQTT Preread](https://en.angie.software//angie/docs/configuration/modules/stream/stream_mqtt_preread.md#stream-mqtt-preread) module that allows
extracting client IDs and usernames from `CONNECT` packets in MQTT
versions [3.1.1](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc398718028)
and [5.0](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901033). | | `--with-stream_rdp_preread_module` | Enables the [RDP Preread](https://en.angie.software//angie/docs/configuration/modules/stream/stream_rdp_preread.md#stream-rdp-preread) module that allows
extracting cookies from RDP sessions. | | `--with-stream_realip_module` | Enables the [RealIP](https://en.angie.software//angie/docs/configuration/modules/stream/stream_realip.md#stream-realip) module
that changes the client address to the address sent in the PROXY protocol
header. | | `--with-stream_ssl_module` | Enables [SSL](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#stream-ssl) support for the
Stream server.

The OpenSSL library is **required** to build and run this module. | | `--with-stream_ssl_preread_module` | Enables the [SSL Preread](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl_preread.md#stream-ssl-preread) module that allows
extracting information from [ClientHello](https://datatracker.ietf.org/doc/html/rfc5246#section-7.4.1.2)
messages without terminating SSL/TLS. | Disabling standard modules: #### \* - `--without-stream_access_module`
- Disables the [Access](https://en.angie.software//angie/docs/configuration/modules/stream/stream_access.md#stream-access)
module that allows limiting access to certain client addresses. | `--without-stream_geo_module` | Disables the [Geo](https://en.angie.software//angie/docs/configuration/modules/stream/stream_geo.md#stream-geo) module that
creates variables with values depending on the client IP address. | |-----------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `--without-stream_limit_conn_module` | Disables the [Limit Conn](https://en.angie.software//angie/docs/configuration/modules/stream/stream_limit_conn.md#stream-limit-conn) module that limits the
number of connections per key, for example, the number of connections
from a single IP address. | | `--without-stream_map_module` | Disables the [Map](https://en.angie.software//angie/docs/configuration/modules/stream/stream_map.md#stream-map) module that
creates variables with values depending on values of other variables. | | `--without-stream_return_module` | Disables the [Return](https://en.angie.software//angie/docs/configuration/modules/stream/stream_return.md#stream-return)
module that sends the specified value to the client and then closes the
connection. | | `--without-stream_set_module` | Disables the [Set](https://en.angie.software//angie/docs/configuration/modules/stream/stream_set.md#stream-set) module that
sets a value for a variable. | | `--without-stream_split_clients_module` | Disables the [Split Clients](https://en.angie.software//angie/docs/configuration/modules/stream/stream_split_clients.md#stream-split-clients) module that creates
variables for A/B testing. | | `--without-stream_upstream_hash_module` | Disables the module that implements the [hash](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-hash) load
balancing method. | | `--without-stream_upstream_least_conn_module` | Disables the module that implements the [least_conn](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-least-conn) load balancing method. | | `--without-stream_upstream_least_time_module` | Disables the module that implements the [least_time](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-least-time) load balancing method. | | `--without-stream_upstream_random_module` | Disables the module that implements the [random](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-random) load
balancing method. | | `--without-stream_upstream_sticky_module` | Disables the module that implements [session persistence](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-sticky), ensuring all requests in the client session are passed
to the same server in the upstream. | | `--without-stream_upstream_zone_module` | Disables the module that enables storing the run-time state of an
upstream in a [shared memory zone](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-zone). | #### Mail Enabling additional modules: #### \* - `--with-mail`, `--with-mail=dynamic`
- Enables the core [Mail](https://en.angie.software//angie/docs/configuration/modules/mail/index.md#mail-core) module
that supports POP3, IMAP4, and SMTP. | `--with-mail_ssl_module` | Enables [SSL](https://en.angie.software//angie/docs/configuration/modules/mail/mail_ssl.md#mail-ssl) support for
the Mail server.

The OpenSSL library is **required** to build and run this module. | |----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| Disabling standard modules: #### \* - `--without-mail_imap_module`
- Disables the [IMAP](https://en.angie.software//angie/docs/configuration/modules/mail/mail_imap.md#mail-imap) protocol in
the Mail server. | `--without-mail_pop3_module` | Disables the [POP3](https://en.angie.software//angie/docs/configuration/modules/mail/mail_pop3.md#mail-pop3) protocol in
the Mail server. | |--------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------| | `--without-mail_smtp_module` | Disables the [SMTP](https://en.angie.software//angie/docs/configuration/modules/mail/mail_smtp.md#mail-smtp) protocol in
the Mail server. | #### Other options #### \* - `--with-cpp_test_module`
- Enables the CPP Test module. It's used primarily for development
and testing purposes and isn't intended for production use. | `--add-module=`path | Enables building an external module at the specified path. | |-----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `--add-dynamic-module=`path | Enables building an external dynamic module at the specified path. | | `--with-compat` | Enables dynamic module compatibility mode. When enabled, Angie can load and
use dynamic modules that were built for the same Angie version,
even if these modules were built with different options. Angie PRO can
load only modules built for Angie PRO; Angie (OSS) modules are rejected due
to a different module signature.
Official packages and images are built without this option. | | `--with-cc=`path | Sets the compiler to be used during the build. | | `--with-cpp=`path | Sets the preprocessor to be used during the build. | | `--with-cc-opt=`parameters | Sets additional parameters that will be added to the `CFLAGS`
variable. When using the system PCRE library under FreeBSD,
`--with-cc-opt="-I /usr/local/include"` should be specified. If the
number of files supported by `select()` needs to be increased, it
can also be specified here, such as `--with-cc-opt="-D
FD_SETSIZE=2048"`. | | `--with-ld-opt=`parameters | Sets additional parameters that will be used during linking. When using
the system PCRE library under FreeBSD, `--with-ld-opt="-L
/usr/local/lib"` should be specified. | | `--with-cpu-opt=`cpu | Enables builds optimized for one of the following processors:
`pentium`, `pentiumpro`, `pentium3`, `pentium4`,
`athlon`, `opteron`, `sparc32`, `sparc64`,
`ppc64`. | ### Examples **Simple HTTPS-Enabled Build**. This basic configuration enables HTTPS support using SSL/TLS, with the necessary dependencies (PCRE for regular expressions, zlib for compression, and OpenSSL for SSL/TLS): ```console $ ./configure \ --sbin-path=/usr/sbin/angie \ --conf-path=/etc/angie/angie.conf \ --pid-path=/run/angie.pid \ --with-http_ssl_module \ --with-pcre=../pcre2-10.40 \ --with-zlib=../zlib-1.3 \ --with-openssl=../openssl-3.0.8 ``` **Performance-Optimized Build**. This configuration is optimized for performance, including HTTP/2 support, **gzip** static compression, JIT for PCRE, and asynchronous I/O; thread pools are also enabled for efficient handling of high loads: ```console $ ./configure \ --sbin-path=/usr/sbin/angie \ --conf-path=/etc/angie/angie.conf \ --pid-path=/run/angie.pid \ --with-http_ssl_module \ --with-http_v2_module \ --with-http_gzip_static_module \ --with-pcre=../pcre2-10.40 \ --with-pcre-jit \ --with-zlib=../zlib-1.3 \ --with-threads \ --with-file-aio ``` **Load Balancer with TCP/UDP Proxying**. This configuration sets up a load balancer for both HTTP and non-HTTP services: ```console $ ./configure \ --sbin-path=/usr/sbin/angie \ --conf-path=/etc/angie/angie.conf \ --pid-path=/run/angie.pid \ --with-stream \ --with-stream_ssl_module \ --with-pcre=../pcre2-10.40 \ --with-zlib=../zlib-1.3 ``` **Specialized Build**. This configuration includes HTTPS, HTTP/2, compression, enhanced security and performance, along with additional modules for Brotli compression and cache management, optimized for both HTTP and TCP/UDP proxying: ```console $ ./configure \ --prefix=/usr/local/angie \ --sbin-path=/usr/sbin/angie \ --conf-path=/etc/angie/angie.conf \ --pid-path=/run/angie.pid \ --lock-path=/var/lock/angie.lock \ --error-log-path=/var/log/angie/error.log \ --http-log-path=/var/log/angie/access.log \ --with-http_ssl_module \ --with-http_v2_module \ --with-http_realip_module \ --with-http_gzip_static_module \ --with-http_stub_status_module \ --with-threads \ --with-file-aio \ --with-stream \ --with-stream_ssl_module \ --with-pcre=../pcre2-10.40 \ --with-pcre-jit \ --with-zlib=../zlib-1.3 \ --with-openssl=../openssl-3.0.8 \ --with-openssl-opt="enable-ec_nistp_64_gcc_128" \ --add-module=../ngx_brotli \ --add-dynamic-module=../ngx_cache_purge ``` The `--add-module` and `--add-dynamic-module` options above reference third-party module sources that you download separately. For example, clone them next to the Angie source tree: ```console $ git clone --recurse-submodules https://github.com/google/ngx_brotli $ git clone https://github.com/nginx-modules/ngx_cache_purge ``` See [Installing Third-Party Modules](https://en.angie.software//angie/docs/installation/external-modules/index.md#install-thirdpartymodules) for the modules Angie packages and their sources. # https://en.angie.software/angie/docs/installation/pro_packages.md # Package Installation of Angie PRO To access the package repository, you need to sign a contract and purchase a license. For questions about licenses, contracts, and custom builds, contact: - [info@wbsrv.ru](mailto:info@wbsrv.ru) - [https://angie.software/](https://angie.software/) - +7 (495) 120 50 33 Then, configure the repository for your distro's package manager to install and update Angie PRO and the [dynamic modules](#install-dynamicmodules-pro) you need. Finally, install the [license file](#install-license) and remove the restrictions. ## Distributions | Name | Versions | Architectures | |-----------------------------------|--------------------------------|-------------------------------| | [AlmaLinux](#install-yum-pro) | 10, 9, 8 | x86-64, arm64 | | [Alpine](#install-alpine-pro) | 3.23, 3.22, 3.21 | x86-64, arm64 | | [ALT](#install-alt-pro) | 11, 10 8 | x86-64, arm64 x86-64 | | [Astra SE](#install-astrase-pro) | 4.7 1.8, 1.7 | arm64 x86-64 | | [CentOS](#install-yum-pro) | 10, 9 | x86-64, arm64 | | [Debian](#install-deb-pro) | 13, 12, 11 | x86-64, arm64 | | [Fedora](#install-yum-pro) | 44, 43 | x86-64, arm64 | | [FreeBSD](#install-freebsd-pro) | 15, 14 | x86-64, arm64 | | [MSVSphere](#install-yum-pro) | 10, 9 8 | x86-64, arm64 x86-64 | | [openSUSE](#install-opensuse-pro) | 16, 15 | x86-64, arm64 | | [Oracle Linux](#install-yum-pro) | 10, 9, 8 | x86-64, arm64 | | [OSNova](#install-osnova-pro) | 3.3.0, 2.13 | x86-64 | | [RED OS](#install-yum-pro) | 8, 7 | x86-64, arm64 | | [Rocky Linux](#install-yum-pro) | 10, 9, 8 | x86-64, arm64 | | [ROSA](#install-yum-pro) | Chrome 13 Chrome 12 Fresh 12 | x86-64 x86-64, arm64 x86-64 | | [SberLinux](#install-yum-pro) | 9 | x86-64 | | [Ubuntu](#install-deb-pro) | 26.04, 24.04, 22.04 | x86-64, arm64 | ### Alma, CentOS, Fedora, MSVSphere, Oracle, RED OS, Rocky, ROSA, SberLinux 1. Create the `/etc/ssl/angie/` directory: ```console $ sudo mkdir -p /etc/ssl/angie/ ``` 2. Transfer the files you received with your license: | File Type | Original Name | Where to Place | |-------------|------------------|---------------------------------| | Certificate | `angie-repo.crt` | `/etc/ssl/angie/angie-repo.crt` | | Private Key | `angie-repo.key` | `/etc/ssl/angie/angie-repo.key` | 3. To add the repository, create the file `/etc/yum.repos.d/angie.repo` with the following content: Alma ```ini [angie-pro] name=Angie PRO repo baseurl=https://download.angie.software/angie-pro/almalinux/$releasever/ sslclientcert=/etc/ssl/angie/angie-repo.crt sslclientkey=/etc/ssl/angie/angie-repo.key gpgcheck=1 enabled=1 gpgkey=https://angie.software/keys/angie-signing.gpg.asc ``` CentOS ```ini [angie-pro] name=Angie PRO repo baseurl=https://download.angie.software/angie-pro/centos/$releasever/ sslclientcert=/etc/ssl/angie/angie-repo.crt sslclientkey=/etc/ssl/angie/angie-repo.key gpgcheck=1 enabled=1 gpgkey=https://angie.software/keys/angie-signing.gpg.asc ``` Fedora ```ini [angie-pro] name=Angie PRO repo baseurl=https://download.angie.software/angie-pro/fedora/$releasever/ sslclientcert=/etc/ssl/angie/angie-repo.crt sslclientkey=/etc/ssl/angie/angie-repo.key gpgcheck=1 enabled=1 gpgkey=https://angie.software/keys/angie-signing.gpg.asc ``` MSVSphere ```ini [angie-pro] name=Angie PRO repo baseurl=https://download.angie.software/angie-pro/msvsphere/$releasever/ sslclientcert=/etc/ssl/angie/angie-repo.crt sslclientkey=/etc/ssl/angie/angie-repo.key gpgcheck=1 enabled=1 gpgkey=https://angie.software/keys/angie-signing.gpg.asc ``` Oracle ```ini [angie-pro] name=Angie PRO repo baseurl=https://download.angie.software/angie-pro/oracle/$releasever/ sslclientcert=/etc/ssl/angie/angie-repo.crt sslclientkey=/etc/ssl/angie/angie-repo.key gpgcheck=1 enabled=1 gpgkey=https://angie.software/keys/angie-signing.gpg.asc ``` RED OS ```ini [angie-pro] name=Angie PRO repo baseurl=https://download.angie.software/angie-pro/redos/$releasever/ sslclientcert=/etc/ssl/angie/angie-repo.crt sslclientkey=/etc/ssl/angie/angie-repo.key gpgcheck=1 enabled=1 gpgkey=https://angie.software/keys/angie-signing.gpg.asc ``` Rocky ```ini [angie-pro] name=Angie PRO repo baseurl=https://download.angie.software/angie-pro/rocky/$releasever/ sslclientcert=/etc/ssl/angie/angie-repo.crt sslclientkey=/etc/ssl/angie/angie-repo.key gpgcheck=1 enabled=1 gpgkey=https://angie.software/keys/angie-signing.gpg.asc ``` ROSA Chrome ```ini [angie-pro] name=Angie PRO repo baseurl=https://download.angie.software/angie-pro/rosa-chrome/$releasever/ sslclientcert=/etc/ssl/angie/angie-repo.crt sslclientkey=/etc/ssl/angie/angie-repo.key gpgcheck=1 enabled=1 gpgkey=https://angie.software/keys/angie-signing.gpg.asc ``` ROSA Fresh ```ini [angie-pro] name=Angie PRO repo baseurl=https://download.angie.software/angie-pro/rosa/$releasever/ sslclientcert=/etc/ssl/angie/angie-repo.crt sslclientkey=/etc/ssl/angie/angie-repo.key gpgcheck=1 enabled=1 gpgkey=https://angie.software/keys/angie-signing.gpg.asc ``` SberLinux ```ini [angie-pro] name=Angie PRO repo baseurl=https://download.angie.software/angie-pro/sberlinux/$releasever/ sslclientcert=/etc/ssl/angie/angie-repo.crt sslclientkey=/etc/ssl/angie/angie-repo.key gpgcheck=1 enabled=1 gpgkey=https://angie.software/keys/angie-signing.gpg.asc ``` 4. Install the Angie PRO package: ```console $ sudo yum install -y angie-pro $ # -- OR -- $ sudo dnf install -y angie-pro ``` 5. (*Optional*) Install any [extra](#install-extras-pro) packages you need: ```console $ sudo yum install -y $ # -- OR -- $ sudo dnf install -y ``` 6. Start the service: ```console $ sudo systemctl start angie ``` 7. To automatically start Angie PRO after server reboot: ```console $ sudo systemctl enable angie ``` ### Alpine 1. Transfer the files you received with your license: | File Type | Original Name | Where to Place | |-------------|------------------|---------------------| | Certificate | `angie-repo.crt` | `/etc/apk/cert.pem` | | Private Key | `angie-repo.key` | `/etc/apk/cert.key` | 2. Install the helper packages for adding the Angie PRO repository: ```console $ sudo apk update $ sudo apk add curl ca-certificates ``` 3. Download the public key of the Angie PRO repository for package verification: ```console $ sudo curl -o /etc/apk/keys/angie-signing.rsa \ https://angie.software/keys/angie-signing.rsa ``` 4. Add the Angie PRO repository: ```console $ echo "https://download.angie.software/angie-pro/alpine/v$(egrep -o \ '[0-9]+\.[0-9]+' /etc/alpine-release)/main" \ | sudo tee -a /etc/apk/repositories > /dev/null ``` 5. Update the repository indexes: ```console $ sudo apk update ``` 6. Install the Angie PRO package: ```console $ sudo apk add angie-pro ``` 7. (*Optional*) Install any [extra](#install-extras-pro) packages you need: ```console $ sudo apk add ``` 8. Start the service: ```console $ sudo service angie start ``` 9. To automatically start Angie PRO after server reboot: ```console $ sudo rc-update add angie ``` ### ALT 1. Create the `/etc/ssl/angie/` directory: ```console $ sudo mkdir -p /etc/ssl/angie/ ``` 2. Transfer the files you received with your license: | File Type | Original Name | Where to Place | |-------------|------------------|---------------------------------| | Certificate | `angie-repo.crt` | `/etc/ssl/angie/angie-repo.crt` | | Private Key | `angie-repo.key` | `/etc/ssl/angie/angie-repo.key` | 3. Download the public key of the Angie PRO repository for package verification: ```console $ curl -o ~/angie-signing.gpg https://angie.software/keys/angie-signing.gpg && \ sudo gpg --no-default-keyring --keyring /usr/lib/alt-gpgkeys/pubring.gpg --import ~/angie-signing.gpg ``` 4. Save the key signature: ```sh $ echo 'simple-key "angie-pro" { Fingerprint "EB8EAF3D4EF1B1ECF34865A2617AB978CB849A76"; Name "Angie PRO (Signing Key) "; }' | sudo tee /etc/apt/vendors.list.d/angie.list > /dev/null ``` 5. Add the Angie PRO repository: ALT 11 ```console $ echo "rpm [angie-pro] https://download.angie.software/angie-pro/altlinux/11/ $(uname -m) main" \ | sudo tee /etc/apt/sources.list.d/angie.list > /dev/null ``` ALT 10 ```console $ echo "rpm [angie-pro] https://download.angie.software/angie-pro/altlinux/10/ $(uname -m) main" \ | sudo tee /etc/apt/sources.list.d/angie.list > /dev/null ``` ALT SP 10 ```console $ echo "rpm [angie-pro] https://download.angie.software/angie-pro/altlinux-sp/10/ $(uname -m) main" \ | sudo tee /etc/apt/sources.list.d/angie.list > /dev/null ``` ALT SP 8 ```console $ echo "rpm [angie-pro] https://download.angie.software/angie-pro/altlinux-sp/8/ $(uname -m) main" \ | sudo tee /etc/apt/sources.list.d/angie.list > /dev/null ``` 6. Create the Angie PRO repository `apt` configuration file in `/etc/apt/apt.conf.d`: ```console $ ( echo 'Acquire::https::Verify-Peer "true";'; echo 'Acquire::https::Verify-Host "true";'; echo 'Acquire::https::SslCert "/etc/ssl/angie/angie-repo.crt";'; echo 'Acquire::https::SslKey "/etc/ssl/angie/angie-repo.key";'; ) | sudo tee -a /etc/apt/apt.conf >/dev/null ``` 7. Update the repository indexes: ```console $ sudo apt-get update ``` 8. Install the Angie PRO package: ```console $ sudo apt-get install -y angie-pro ``` 9. (*Optional*) Install any [extra](#install-extras-pro) packages you need: ```console $ sudo apt-get install -y ``` 10. Start the service: ```console $ sudo systemctl start angie ``` 11. To automatically start Angie PRO after server reboot: ```console $ sudo systemctl enable angie ``` ### Astra SE 1. Create the `/etc/ssl/angie/` directory: ```console $ sudo mkdir -p /etc/ssl/angie/ ``` 2. Transfer the files you received with your license: | File Type | Original Name | Where to Place | |-------------|------------------|---------------------------------| | Certificate | `angie-repo.crt` | `/etc/ssl/angie/angie-repo.crt` | | Private Key | `angie-repo.key` | `/etc/ssl/angie/angie-repo.key` | Restrict access to the directory and files: ```console $ sudo chown -R _apt:nogroup /etc/ssl/angie/ ``` 3. Install the helper packages for adding the Angie PRO repository: ```console $ sudo apt-get update $ sudo apt-get install -y apt-transport-https lsb-release \ ca-certificates curl gnupg2 ``` 4. Download the public key of the Angie PRO repository for package verification: ```console $ sudo curl -o /etc/apt/trusted.gpg.d/angie-signing.gpg \ https://angie.software/keys/angie-signing.gpg ``` 5. Add the Angie PRO repository: ```console $ echo "deb https://download.angie.software/angie-pro/astra-se/$(egrep -o \ '[0-9]+\.[0-9]+' /etc/astra_version) unstable main" \ | sudo tee /etc/apt/sources.list.d/angie.list > /dev/null ``` 6. To configure the repository, create a file `/etc/apt/apt.conf.d/90download-angie` with the following contents: ```console Acquire::https::download.angie.software::Verify-Peer "true"; Acquire::https::download.angie.software::Verify-Host "true"; Acquire::https::download.angie.software::SslCert "/etc/ssl/angie/angie-repo.crt"; Acquire::https::download.angie.software::SslKey "/etc/ssl/angie/angie-repo.key"; ``` 7. Update the repository indexes: ```console $ sudo apt-get update ``` 8. (*Optional*) When running in Closed Software Environment mode ([CSE](https://wiki.astralinux.ru/pages/viewpage.action?pageId=41190634)), install the key package for verifying the authenticity of Angie PRO executable files: ```console $ sudo apt-get install -y angie-digsig-key ``` Update the CSE: ```console $ sudo update-initramfs -uk all ``` Then **restart the server**: ```console $ sudo shutdown -r now ``` 9. Install the Angie PRO package: ```console $ sudo apt-get install -y angie-pro ``` 10. (*Optional*) Install any [extra](#install-extras-pro) packages you need: ```console $ sudo apt-get install -y ``` ### Debian, Ubuntu 1. Create the `/etc/ssl/angie/` directory: ```console $ sudo mkdir -p /etc/ssl/angie/ ``` 2. Transfer the files you received with your license: | File Type | Original Name | Where | |-------------|------------------|---------------------------------| | Certificate | `angie-repo.crt` | `/etc/ssl/angie/angie-repo.crt` | | Private Key | `angie-repo.key` | `/etc/ssl/angie/angie-repo.key` | Restrict access to the directory and files: ```console $ sudo chown -R _apt:nogroup /etc/ssl/angie/ ``` 3. Install the prerequisites for adding the Angie PRO repo: ```console $ sudo apt-get update $ sudo apt-get install -y apt-transport-https lsb-release \ ca-certificates curl gnupg2 ``` 4. Download the public key of the Angie PRO repo for package verification: ```console $ sudo curl -o /etc/apt/trusted.gpg.d/angie-signing.gpg \ https://angie.software/keys/angie-signing.gpg ``` 5. Add the Angie PRO repo: ```console $ echo "deb https://download.angie.software/angie-pro/$(. /etc/os-release && echo "$ID/$VERSION_ID $VERSION_CODENAME") main" \ | sudo tee /etc/apt/sources.list.d/angie.list > /dev/null ``` 6. To configure the repo, create a file named `/etc/apt/apt.conf.d/90download-angie` with the following contents: ```console Acquire::https::download.angie.software::Verify-Peer "true"; Acquire::https::download.angie.software::Verify-Host "true"; Acquire::https::download.angie.software::SslCert "/etc/ssl/angie/angie-repo.crt"; Acquire::https::download.angie.software::SslKey "/etc/ssl/angie/angie-repo.key"; ``` 7. Update the repo indexes: ```console $ sudo apt-get update ``` 8. Install the Angie PRO package: ```console $ sudo apt-get install -y angie-pro ``` 9. (*Optional*) Install any [extra](#install-extras-pro) packages you need: ```console $ sudo apt-get install -y ``` ### OSNova 1. Install the prerequisites for adding the Angie PRO repo: ```console $ sudo apt-get update $ sudo apt-get install -y ca-certificates curl ``` 2. Download the public key of the Angie PRO repo for package verification: ```console $ sudo curl -o /etc/apt/trusted.gpg.d/angie-signing.gpg \ https://angie.software/keys/angie-signing.gpg ``` 3. Add the Angie PRO repo: ```console $ echo "deb https://download.angie.software/angie-pro/osnova/$(egrep -o \ '[0-9]*' /etc/osnova_version | head -1) \ $(. /etc/os-release && echo "$VERSION_CODENAME") main" \ | sudo tee /etc/apt/sources.list.d/angie.list > /dev/null ``` 4. Update the repo indexes: ```console $ sudo apt-get update ``` 5. Install the Angie PRO package: ```console $ sudo apt-get install -y angie ``` 6. (*Optional*) Install any [extra](#install-extras-pro) packages you need: ```console $ sudo apt-get install -y ``` ### FreeBSD 1. To add the Angie PRO repo, create these directories: ```console $ sudo mkdir -p /usr/local/etc/pkg/angie/ /usr/local/etc/pkg/repos/ ``` 2. To configure the repo, create a file named `/usr/local/etc/pkg/repos/angie.conf` with the following contents: ```pkgconfig angie: { url: "https://download.angie.software/angie-pro/freebsd/${VERSION_MAJOR}/${ARCH}", signature_type: "pubkey", pubkey: "/usr/local/etc/pkg/angie/angie-signing.rsa", enabled: yes } ``` 3. Download the public key of the Angie PRO repo for package verification: ```console $ sudo curl -o /usr/local/etc/pkg/angie/angie-signing.rsa \ https://angie.software/keys/angie-signing.rsa ``` 4. Transfer the files you received with your license: | File Type | Original Name | Where | |-------------|------------------|-------------------------------------------| | Certificate | `angie-repo.crt` | `/usr/local/etc/pkg/angie/angie-repo.crt` | | Private Key | `angie-repo.key` | `/usr/local/etc/pkg/angie/angie-repo.key` | 5. Add the certificate and the key to the package manager's configuration: ```sh $ echo ' PKG_ENV: { SSL_CLIENT_CERT_FILE: "/usr/local/etc/pkg/angie/angie-repo.crt", SSL_CLIENT_KEY_FILE: "/usr/local/etc/pkg/angie/angie-repo.key" }' | sudo tee -a /usr/local/etc/pkg.conf > /dev/null ``` 6. Update the repo indexes: ```console $ sudo pkg update ``` 7. Install the Angie PRO package: ```console $ sudo pkg install -r angie -y angie-pro ``` 8. (*Optional*) Install any [extra](#install-extras-pro) packages you need: ```console $ sudo pkg install -r angie -y ``` 9. Start the service: ```console $ sudo service angie start ``` 10. To autostart Angie PRO after server reboot: ```console $ sudo sysrc angie_enable=YES ``` #### NOTE Since the FreeBSD package manager may incorrectly determine the latest version, use the following approach to update already installed packages: ```console $ sudo pkg upgrade `pkg search -r angie angie-pro-[0-9] | sort -Vr | head -1 | awk {'print $1'}` ``` ### openSUSE 1. Create the `/etc/ssl/angie/` directory: ```console $ sudo mkdir -p /etc/ssl/angie/ ``` 2. Transfer the files you received with your license: | File Type | Original Name | Where | |-------------|------------------|---------------------------------| | Certificate | `angie-repo.crt` | `/etc/ssl/angie/angie-repo.crt` | | Private Key | `angie-repo.key` | `/etc/ssl/angie/angie-repo.key` | Then combine them into a bundle `/etc/ssl/angie/angie-repo-bundle.crt`: ```console $ cat /etc/ssl/angie/angie-repo.crt /etc/ssl/angie/angie-repo.key | \ sudo tee -a /etc/ssl/angie/angie-repo-bundle.crt > /dev/null ``` 3. To add the repository, create a file named `/etc/zypp/repos.d/angie.repo` with the following contents: ```ini [angie-pro] enabled=1 autorefresh=1 baseurl=https://download.angie.software/angie-pro/opensuse/$releasever_major?ssl_clientcert=/etc/ssl/angie/angie-repo-bundle.crt&ssl_verify=peer gpgcheck=1 gpgkey=https://angie.software/keys/angie-signing.gpg.asc ``` 4. Update the repo indexes: ```console $ sudo zypper refresh ``` 5. Install the Angie PRO package: ```console $ sudo zypper install -y angie-pro ``` 6. (*Optional*) Install any [extra](#install-extras-pro) packages you need: ```console $ sudo zypper install -y ``` 7. Start the service: ```console $ sudo systemctl start angie ``` 8. To automatically start Angie PRO after server reboot: ```console $ sudo systemctl enable angie ``` ## Extras In addition to packages that provide core functionality, we also publish several additional packages, both our own and from selected third-party sources. ### Console Light Web Panel Console Light is a lightweight [monitoring web panel](https://en.angie.software//angie/docs/configuration/monitoring.md#monitoring) for Angie PRO, published in our repositories as the `angie-pro-console-light` package. It's installed the same way as the `angie` package in the instructions above; for configuration instructions, see the [Console Light Web Monitoring Panel](https://en.angie.software//angie/docs/configuration/monitoring.md#monitoring) section. ### Dynamic Modules To extend the basic functionality of Angie PRO, you can add various dynamic modules. You can get them as ready-made packages from our repository: | [angie-pro-module-image-filter](https://en.angie.software//angie/docs/configuration/modules/http/http_image_filter.md#http-image-filter) | Adds image transformations for JPEG, GIF, PNG, and WebP formats. | |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------| | angie-pro-module-njs:
[HTTP JS](https://en.angie.software//angie/docs/configuration/modules/external-modules/http_js.md#http-js),
[Stream JS](https://en.angie.software//angie/docs/configuration/modules/external-modules/stream_js.md#stream-js) | Allow using the njs language (a subset of JavaScript)
in Angie PRO configuration in `http` and `stream` contexts respectively. | | [angie-pro-module-perl](https://en.angie.software//angie/docs/configuration/modules/http/http_perl.md#http-perl) | Allows writing `location` and variable handlers in Perl,
as well as calling Perl from SSI. | | [angie-pro-module-xslt](https://en.angie.software//angie/docs/configuration/modules/http/http_xslt.md#http-xslt) | Adds a filter that transforms XML responses using XSLT templates. | To apply an installed module in your [configuration](https://en.angie.software//angie/docs/configuration/configfile.md#configfile), load it using the [load_module](https://en.angie.software//angie/docs/configuration/modules/core.md#load-module) directive in the `main` context: ```nginx load_module modules/.so; ``` A wide range of [third-party modules](https://en.angie.software//angie/docs/installation/external-modules/index.md#install-thirdpartymodules) is also available. ## License File To configure the license for Angie PRO: 1. Save the license file as `/etc/angie/license.pem`, setting the same permissions you use for your [client certificates](https://en.angie.software//angie/docs/configuration/ssl.md#ssl-config). 2. Verify the license is valid; otherwise, check the details: ```console $ sudo angie -t angie: Valid license found: angie: - owner: CN=Angie Client License angie: - period: Jul 8 21:00:00 2024 GMT .. Jul 17 20:59:59 2024 GMT angie: angie: Limitations: angie: - worker_processes_limit: 8 angie: - worker_connections_limit: 0 ``` 3. Monitor the console and logs for any licensing issues. If the license expires during operation, Angie PRO periodically issues corresponding warnings. Additionally, on reload, configuration error messages will appear if, for example, the number of worker processes specified in the license terms is exceeded. 4. Modify the `/etc/angie/angie.conf` file; after installation, two parameters in it limit operation: ```nginx worker_processes 1; worker_connections 256; ``` After saving the license file, change them according to your license terms, for example: ```nginx worker_processes 8; worker_connections 65535; ``` # https://en.angie.software/angie/docs/installation/external-modules.md # Installing Third-Party Modules In addition to our own dynamic modules for [Angie](https://en.angie.software//angie/docs/installation/oss_packages.md#install-dynamicmodules-oss) and [Angie PRO](https://en.angie.software//angie/docs/installation/pro_packages.md#install-dynamicmodules-pro), we collect and publish packages for a number of popular nginx-compatible third-party modules, developed outside our company, in our repository. ## Installation and Configuration Third-party module packages are installed from our repository just like our own packages: - [Angie](https://en.angie.software//angie/docs/installation/oss_packages.md#oss-packages) - [Angie PRO](https://en.angie.software//angie/docs/installation/pro_packages.md#pro-packages) To use the installed module in [configuration](https://en.angie.software//angie/docs/configuration/configfile.md#configfile), load it using the [load_module](https://en.angie.software//angie/docs/configuration/modules/core.md#load-module) directive in the `main` context: ```nginx load_module modules/.so; ``` #### NOTE We do not review the source code of these modules and are not responsible for the consequences of their installation; the packages are compiled based on numerous requests *exclusively* for user convenience. ## List of Packages | Module | Version | Packages | |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------| | [Auth JWT](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-jwt.md#external-auth-jwt) | [0.14.2](https://github.com/kjdev/nginx-auth-jwt) | `angie-module-auth-jwt` `angie-pro-module-auth-jwt` | | [Auth LDAP](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-ldap.md#external-ldap) | [241200e](https://github.com/kvspb/nginx-auth-ldap) | `angie-module-auth-ldap` `angie-pro-module-auth-ldap` | | [Auth PAM](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-pam.md#external-auth-pam) | [v1.5.5](https://github.com/sto/ngx_http_auth_pam_module) | `angie-module-auth-pam` `angie-pro-module-auth-pam` | | [Auth SPNEGO](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-spnego.md#external-auth-spnego) | [v1.1.3](https://github.com/stnoonan/spnego-http-auth-nginx-module) | `angie-module-auth-spnego` `angie-pro-module-auth-spnego` | | [Auth TOTP](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-totp.md#external-auth-totp) | [1.2.0](https://github.com/61131/nginx-http-auth-totp) | `angie-module-auth-totp` `angie-pro-module-auth-totp` | | [Brotli](https://en.angie.software//angie/docs/configuration/modules/external-modules/brotli.md#external-brotli) | [v1.0.0rc](https://github.com/google/ngx_brotli) | `angie-module-brotli` `angie-pro-module-brotli` | | [Cache Purge](https://en.angie.software//angie/docs/configuration/modules/external-modules/cache-purge.md#external-cache-purge) | [3.0.2](https://github.com/nginx-modules/ngx_cache_purge) | `angie-module-cache-purge` `angie-pro-module-cache-purge` | | [CGI](https://en.angie.software//angie/docs/configuration/modules/external-modules/cgi.md#external-cgi) | [v0.15](https://github.com/pjincz/nginx-cgi) | `angie-module-cgi` `angie-pro-module-cgi` | | [Combined Upstreams](https://en.angie.software//angie/docs/configuration/modules/external-modules/combined-upstreams.md#external-combined-upstreams) | [2.3.1](https://github.com/lyokha/nginx-combined-upstreams-module) | `angie-module-combined-upstreams` `angie-pro-module-combined-upstreams` | | [DAV Ext](https://en.angie.software//angie/docs/configuration/modules/external-modules/dav-ext.md#external-dav-ext) | [v4.0.1](https://github.com/arut/nginx-dav-ext-module) | `angie-module-dav-ext` `angie-pro-module-dav-ext` | | [Dynamic Limit Req](https://en.angie.software//angie/docs/configuration/modules/external-modules/dynamic-limit-req.md#external-dynamic-limit-req) | [1.9.3](https://github.com/limithit/ngx_dynamic_limit_req_module) | `angie-module-dynamic-limit-req` `angie-pro-module-dynamic-limit-req` | | [Echo](https://en.angie.software//angie/docs/configuration/modules/external-modules/echo.md#external-echo) | [v0.64](https://github.com/openresty/echo-nginx-module) | `angie-module-echo` `angie-pro-module-echo` | | [Enhanced Memcached](https://en.angie.software//angie/docs/configuration/modules/external-modules/enhanced-memcached.md#external-enhanced-memcached) | [v0.3](https://github.com/bpaquet/ngx_http_enhanced_memcached_module) | `angie-module-enhanced-memcached` `angie-pro-module-enhanced-memcached` | | [Eval](https://en.angie.software//angie/docs/configuration/modules/external-modules/eval.md#external-eval) | [2016.06.10](https://github.com/openresty/nginx-eval-module) | `angie-module-eval` `angie-pro-module-eval` | | [GeoIP2](https://en.angie.software//angie/docs/configuration/modules/external-modules/geoip2.md#external-geoip2) | [3.4](https://github.com/leev/ngx_http_geoip2_module) | `angie-module-geoip2` `angie-pro-module-geoip2` | | [Headers More](https://en.angie.software//angie/docs/configuration/modules/external-modules/headers-more.md#external-headers-more) | [v0.39](https://github.com/openresty/headers-more-nginx-module) | `angie-module-headers-more` `angie-pro-module-headers-more` | | [HTTP Auth RADIUS](https://en.angie.software//angie/docs/configuration/modules/external-modules/http-auth-radius.md#external-http-auth-radius) | [458af16](https://github.com/ten0s/ngx_http_auth_radius_module) | `angie-module-http-auth-radius` `angie-pro-module-http-auth-radius` | | [JWT](https://en.angie.software//angie/docs/configuration/modules/external-modules/jwt.md#external-jwt) | [v3.4.4](https://github.com/max-lt/nginx-jwt-module) | `angie-module-jwt` `angie-pro-module-jwt` | | [Keyval](https://en.angie.software//angie/docs/configuration/modules/external-modules/keyval.md#external-keyval) | [0.5.0](https://github.com/kjdev/nginx-keyval) | `angie-module-keyval` `angie-pro-module-keyval` | | [Lua](https://en.angie.software//angie/docs/configuration/modules/external-modules/lua.md#external-lua):
[http_lua_module](https://github.com/openresty/lua-nginx-module),
[stream_lua_module](https://github.com/openresty/stream-lua-nginx-module) | [0.10.31](https://github.com/openresty/lua-nginx-module) /
[v0.0.17](https://github.com/openresty/stream-lua-nginx-module) | `angie-module-lua` `angie-pro-module-lua` | | [ModSecurity](https://en.angie.software//angie/docs/configuration/modules/external-modules/modsecurity.md#external-modsec) | [v1.0.4](https://github.com/owasp-modsecurity/ModSecurity-nginx) | `angie-module-modsecurity` `angie-pro-module-modsecurity` | | [NJS](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs):
[http_js](https://en.angie.software//angie/docs/configuration/modules/external-modules/http_js.md#http-js),
[stream_js](https://en.angie.software//angie/docs/configuration/modules/external-modules/stream_js.md#stream-js) | [1.0.0](https://nginx.org/en/docs/njs/) | `angie-module-njs` `angie-pro-module-njs` | | [NDK](https://en.angie.software//angie/docs/configuration/modules/external-modules/ndk.md#external-ndk) | [v0.3.4](https://github.com/vision5/ngx_devel_kit) | `angie-module-ndk` `angie-pro-module-ndk` | | [OpenTracing](https://en.angie.software//angie/docs/configuration/modules/external-modules/opentracing.md#external-opentracing) | [0.48.0](https://github.com/opentracing-contrib/nginx-opentracing) | `angie-module-opentracing` `angie-pro-module-opentracing` | | [OpenTelemetry](https://en.angie.software//angie/docs/configuration/modules/external-modules/otel.md#external-otel) | [v0.1.2](https://github.com/nginxinc/nginx-otel) | `angie-module-otel` `angie-pro-module-otel` | | [PostgreSQL](https://en.angie.software//angie/docs/configuration/modules/external-modules/postgres.md#external-postgres) | [1.0rc7](https://github.com/FRiCKLE/ngx_postgres) | `angie-module-postgres` `angie-pro-module-postgres` | | [Redis2](https://en.angie.software//angie/docs/configuration/modules/external-modules/redis2.md#external-redis2) | [v0.15](https://github.com/openresty/redis2-nginx-module) | `angie-module-redis2` `angie-pro-module-redis2` | | [RTMP](https://en.angie.software//angie/docs/configuration/modules/external-modules/rtmp.md#external-rtmp) | [v1.2.2](https://github.com/arut/nginx-rtmp-module) | `angie-module-rtmp` `angie-pro-module-rtmp` | | [Set Misc](https://en.angie.software//angie/docs/configuration/modules/external-modules/set-misc.md#external-set-misc) | [v0.33](https://github.com/openresty/set-misc-nginx-module) | `angie-module-set-misc` `angie-pro-module-set-misc` | | [Subs](https://en.angie.software//angie/docs/configuration/modules/external-modules/subs.md#external-subs) | [e12e965](https://github.com/yaoweibin/ngx_http_substitutions_filter_module) | `angie-module-subs` `angie-pro-module-subs` | | [TestCookie](https://en.angie.software//angie/docs/configuration/modules/external-modules/testcookie.md#external-testcookie) | [7d263d4](https://github.com/kyprizel/testcookie-nginx-module) | `angie-module-testcookie` `angie-pro-module-testcookie` | | [UnBrotli](https://en.angie.software//angie/docs/configuration/modules/external-modules/unbrotli.md#external-unbrotli) | [60bed63](https://github.com/clyfish/ngx_unbrotli) | `angie-module-unbrotli` `angie-pro-module-unbrotli` | | [Upload](https://en.angie.software//angie/docs/configuration/modules/external-modules/upload.md#external-upload) | [2.3.0](https://github.com/fdintino/nginx-upload-module) | `angie-module-upload` `angie-pro-module-upload` | | [VOD](https://en.angie.software//angie/docs/configuration/modules/external-modules/vod.md#external-vod) | [1.9.0](https://github.com/kaltura/nginx-vod-module) | `angie-module-vod` `angie-pro-module-vod` | | [VTS](https://en.angie.software//angie/docs/configuration/modules/external-modules/vts.md#external-vts):
[module-vts](https://github.com/vozlt/nginx-module-vts),
[module-sts](https://github.com/vozlt/nginx-module-sts),
[module-stream-sts](https://github.com/vozlt/nginx-module-stream-sts) | [v0.2.5](https://github.com/vozlt/nginx-module-vts) /
[v0.1.1](https://github.com/vozlt/nginx-module-sts) /
[v0.1.1](https://github.com/vozlt/nginx-module-stream-sts) | `angie-module-vts` `angie-pro-module-vts` | | [ZIP](https://en.angie.software//angie/docs/configuration/modules/external-modules/zip.md#external-zip) | [1.3.0](https://github.com/evanmiller/mod_zip) | `angie-module-zip` `angie-pro-module-zip` | | [Zstd](https://en.angie.software//angie/docs/configuration/modules/external-modules/zstd.md#external-zstd) | [f4ba115](https://github.com/tokers/zstd-nginx-module) | `angie-module-zstd` `angie-pro-module-zstd` | # https://en.angie.software/angie/docs/installation/thirdparty.md # Third-Party Repositories for Angie We recommend using our official packages to install Angie: - [Angie](https://en.angie.software//angie/docs/installation/oss_packages.md#oss-packages) - [Angie PRO](https://en.angie.software//angie/docs/installation/pro_packages.md#pro-packages) If you wish to use third-party repositories that are specific to your system or distribution, the following options are currently available. Official repositories of various Linux distributions: - [ALT Linux](https://packages.altlinux.org/ru/sisyphus/srpms/angie/) - [Arch User Repository](https://aur.archlinux.org/packages/angie) - [FreeBSD FreshPorts](https://www.freshports.org/www/angie/) - [nixpkgs](https://github.com/NixOS/nixpkgs/blob/nixos-unstable/pkgs/servers/http/angie/default.nix) - [ROSA Linux ABF](https://abf.io/import/angie/) Package managers for macOS: - [Homebrew](https://github.com/stychos/homebrew-angie): ```console $ brew tap stychos/angie $ brew install stychos/angie/angie ``` - [MacPorts](https://github.com/macports/macports-ports/tree/master/www/angie): ```console $ sudo port install angie ``` For an additional list of third-party sources, see [here](https://repology.org/project/angie/versions). #### NOTE We do not publish anything in these repositories and are not responsible for the consequences of installing software from them. # https://en.angie.software/angie/docs/configuration.md # Configuration This page contains articles, references, indexes, and instructions for configuring Angie. ## General Information These articles cover installation and configuration of Angie, starting and stopping the web server, managing it, as well as various aspects of request processing and interaction with other servers. * [Configuration](https://en.angie.software//angie/docs/configuration/configfile.md) * [Management](https://en.angie.software//angie/docs/configuration/runtime.md) * [Connections, Sessions, Requests, Logs](https://en.angie.software//angie/docs/configuration/processing.md) ## References and Indexes These summary sections provide reference information on built-in modules, examples of their configuration, as well as supported directives and variables. * [Modules](https://en.angie.software//angie/docs/configuration/modules/index.md) * [Variables](https://en.angie.software//angie/docs/configuration/varindex.md) * [NJS API Reference](https://en.angie.software//angie/docs/configuration/njs-reference.md) You can also use the short link service at [https://angie.ws/](https://angie.ws/) to quickly find individual directives and variables: * [Quick Access](https://en.angie.software//angie/docs/configuration/quickaccess.md) ## Instructions Step-by-step instructions for specific aspects of configuring Angie are provided here. * [Configuring ACME](https://en.angie.software//angie/docs/configuration/acme.md) * [Configuring clusters](https://en.angie.software//angie/docs/configuration/cluster.md) * [Configuring OIDC](https://en.angie.software//angie/docs/configuration/oidc.md) * [Configuring SSL](https://en.angie.software//angie/docs/configuration/ssl.md) * [Console Light Panel](https://en.angie.software//angie/docs/configuration/monitoring.md) * [Custom metrics](https://en.angie.software//angie/docs/configuration/custom-metrics.md) * [Migrating from nginx](https://en.angie.software//angie/docs/configuration/migration.md) * [Unsupported nginx Directives](https://en.angie.software//angie/docs/configuration/nginx-unsupported-directives.md) * [Grafana Panel](https://en.angie.software//angie/docs/configuration/grafana.md) ## Community Materials We have collected community resources that will help you better understand configuring and using Angie. ### Articles - [Angie: A New NGINX Fork Developed by Some of Its Former Devs](https://linuxiac.com/angie-web-server-is-a-new-nginx-fork/) on Linuxiac - [What's New in the Angie 1.9 Web Server (an nginx fork) and What to Expect from 1.10?](https://habr.com/en/articles/911444/) on Habr ### Courses English-language courses on Angie are not currently available. Refer to the official Angie documentation and the practical guides below. ### Practical Guides - [Migrating from Nginx to Angie: A Real-World Journey from Certbot to Built-in ACME](https://dev.to/stan-breaks/migrating-from-nginx-to-angie-a-real-world-journey-from-certbot-to-built-in-acme-7a3) on DEV Community ### Interviews and Podcasts - "NGINX is Dead? // Angie Web Server Migration Guide" by DevOps Toolbox ([YouTube](https://www.youtube.com/watch?v=HFCtaiJMDGg), 27.03.2026) - "Nginx Has a BIG Problem..." by DevOps Toolbox ([YouTube](https://www.youtube.com/watch?v=acJBNVTW42I), 30.01.2026) ## Documentation for AI Assistants The site ships machine-readable copies of every documentation page so that LLM-powered tools — Claude Code, Cursor, ChatGPT, and other agentic assistants — can ingest the content directly instead of scraping rendered HTML. ### llms.txt and llms-full.txt Each language subdomain serves an [llms.txt](https://llmstxt.org/) sitemap with a short project description and a list of every page (title, absolute URL, annotation). Its companion `llms-full.txt` concatenates the full Markdown body of every page into a single file suitable for one-shot ingestion: - [https://en.angie.software/llms.txt](https://en.angie.software/llms.txt) - [https://en.angie.software/llms-full.txt](https://en.angie.software/llms-full.txt) These URLs are also advertised in [robots.txt](https://en.angie.software/robots.txt) via the `Llms:` directive, so LLM crawlers discover them automatically. ### Markdown versions of pages Every HTML page has a Markdown twin. To fetch the Markdown version of any documentation URL, replace the trailing slash with `.md`: - HTML: [https://en.angie.software/angie/docs/configuration/](https://en.angie.software/angie/docs/configuration/) - Markdown: [https://en.angie.software/angie/docs/configuration.md](https://en.angie.software/angie/docs/configuration.md) Markdown is generated from the same reStructuredText source as the HTML build, so the content always stays in sync. ### Context7 Angie documentation is indexed on [Context7](https://context7.com/), a registry that serves up-to-date library documentation to AI code editors through its MCP server. The English Angie listing is at [https://context7.com/websites/en_angie_software_angie](https://context7.com/websites/en_angie_software_angie). # https://en.angie.software/angie/docs/configuration/configfile.md # Configuration Files Angie uses a text-based configuration file. By default, this file is named `angie.conf` and is located according to the [--conf-path](https://en.angie.software//angie/docs/installation/sourcebuild.md#paths) build parameter, typically in the `/etc/angie` directory. A configuration file generally consists of the following contexts: - [events](https://en.angie.software//angie/docs/configuration/modules/core.md#events) – General connection processing - [http](https://en.angie.software//angie/docs/configuration/modules/http/index.md#d-http) – HTTP traffic - [mail](https://en.angie.software//angie/docs/configuration/modules/mail/index.md#m-mail) – Mail traffic - [stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#s-stream) – TCP and UDP traffic - [wasm_modules](https://en.angie.software//angie/docs/configuration/modules/wasm/index.md#wasm-modules) – WASM runtime Directives that are placed outside of these contexts are considered to be in the `main` context: ```nginx user angie; # a directive in the 'main' context events { # configuration of connection processing } http { # Configuration specific to HTTP and affecting all virtual servers server { # configuration of HTTP virtual server 1 location /one { # configuration for processing URIs starting with '/one' } location /two { # configuration for processing URIs starting with '/two' } } server { # configuration of HTTP virtual server 2 } } stream { # Configuration specific to TCP/UDP and affecting all virtual servers server { # configuration of TCP virtual server 1 } } ``` To simplify configuration management, we recommend using the [include](https://en.angie.software//angie/docs/configuration/modules/core.md#include) directive in the main `angie.conf` file to reference the contents of feature-specific files: ```nginx include /etc/angie/http.d/*.conf; include /etc/angie/stream.d/*.conf; ``` ## Inheritance In general, a child context (one that is contained within another context, which is considered its parent) inherits the settings of directives defined at the parent level. Some directives can appear in multiple contexts; in such cases, you can override the settings inherited from the parent by including the directive in the child context. ## Syntax ### Measurement Units You can specify sizes using the following units: | No suffix | Bytes | |-------------|-----------| | `k`, `K` | Kilobytes | | `m`, `M` | Megabytes | | `g`, `G` | Gigabytes | For example: `1024`, `8k`, `1m`. The `g` suffix is accepted only by [client_max_body_size](https://en.angie.software//angie/docs/configuration/modules/http/index.md#client-max-body-size), [directio](https://en.angie.software//angie/docs/configuration/modules/http/index.md#directio), [directio_alignment](https://en.angie.software//angie/docs/configuration/modules/http/index.md#directio-alignment), [worker_rlimit_core](https://en.angie.software//angie/docs/configuration/modules/core.md#worker-rlimit-core), [proxy_cache_max_range_offset](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-max-range-offset), and the `max_size` and `min_free` parameters of [proxy_cache_path](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-path). The `fastcgi_`, `scgi_`, and `uwsgi_` counterparts of the two caching directives accept it as well. Every other size takes no suffix larger than `m`, including buffer and shared memory zone sizes: `proxy_buffer_size 1g;` is a configuration error. The same limit applies to sizes that measure a file: [proxy_max_temp_file_size](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-max-temp-file-size) defaults to `1024m` but rejects `1g`. Time intervals can be specified in milliseconds, seconds, minutes, hours, days, and so on, using the following suffixes: | `ms` | Milliseconds | |--------|-----------------------------------| | `s` | Seconds | | `m` | Minutes | | `h` | Hours | | `d` | Days | | `w` | Weeks | | `M` | Months (assumed equal to 30 days) | | `y` | Years (assumed equal to 365 days) | Multiple units can be combined in a single value by specifying them in order from the most significant to the least significant, optionally separated by whitespace. For example, `"1h 30m"` specifies the same duration as `"90m"` or `"5400s"`. A value without a suffix is interpreted as seconds. It is recommended to always specify a suffix. Some time intervals can only be specified with second-level resolution. ### Directives Each directive consists of a name and a set of parameters. If any part of a directive needs to contain spaces, it should be enclosed in quotes or escape the spaces: ```nginx add_header X-MyHeader "foo bar"; add_header X-MyHeader foo\ bar; ``` If a named parameter needs spaces and you use quotes, its name must be enclosed in quotes as well: ```nginx server example.com "sid=server 1"; ``` ### Strings with Variables Many directives accept a *string with variables* (also called a *complex value*): a parameter value that mixes literal text with variable references such as `$name`, `${name}`, and the regular-expression capture variables `$1` to `$9`. Such a value is compiled once when the configuration is loaded and re-evaluated for every request or connection, so the resulting string can differ from one request to the next. A value that contains no `$` behaves as a plain literal and adds no per-request overhead. Use the braced form `${name}` to separate a variable name from text that immediately follows it, as in `${name}_suffix`. The capture variables `$1` to `$9` are available only where a regular expression with the corresponding groups has matched, and require a build with PCRE. There is no backslash escaping of `$`. To include a literal `$`, define a variable that holds it, for example with [map](https://en.angie.software//angie/docs/configuration/modules/http/http_map.md#id1) or [set](https://en.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#set), and reference that variable in the value. The available variables depend on the context: those in the [http](https://en.angie.software//angie/docs/configuration/modules/http/index.md#d-http) subsystem differ from those in the [stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#s-stream) subsystem; see the [variable index](https://en.angie.software//angie/docs/configuration/varindex.md#varindex) for the full list. Variables are produced both by built-in modules and by directives such as [map](https://en.angie.software//angie/docs/configuration/modules/http/http_map.md#id1), [geo](https://en.angie.software//angie/docs/configuration/modules/http/http_geo.md#id1), and [split_clients](https://en.angie.software//angie/docs/configuration/modules/http/http_split_clients.md#id1). For some directives the presence of a variable changes runtime behavior: the value is then resolved dynamically per request rather than fixed at configuration load, which may require a [resolver](https://en.angie.software//angie/docs/configuration/modules/http/index.md#resolver). The [proxy_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass) directive is one such case. ## Setting Up Hashes To efficiently process static sets of data, such as server names, the [map](https://en.angie.software//angie/docs/configuration/modules/http/http_map.md#id1) directive values, MIME types, and request header names, Angie utilizes hash tables. During startup and each reconfiguration, Angie determines the optimal size for these hash tables to ensure that the bucket size, which stores keys with identical hash values, does not exceed the configured parameter (hash bucket size). The table size is measured in buckets and is adjusted until it exceeds the hash max size parameter. Most hash tables have corresponding directives to adjust these parameters, such as [server_names_hash_max_size](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server-names-hash-max-size) and [server_names_hash_bucket_size](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server-names-hash-bucket-size) for server names. The hash bucket size parameter is aligned to a multiple of the processor's cache line size. This alignment enhances key search efficiency on modern processors by reducing the number of memory accesses. If the hash bucket size is equal to one cache line size, the maximum number of memory accesses during a key search will be two: one to compute the bucket address and another to search inside the bucket. Therefore, if Angie indicates that either the hash max size or hash bucket size should be increased, start by increasing the hash max size. ### Reloading Configuration To apply changes to the configuration file, it must be reloaded. You can either restart the Angie process with a configuration syntax check beforehand: ```console $ sudo angie -t && sudo service angie restart ``` Alternatively, you can reload the service to apply the new configuration without interrupting the processing of current requests: ```console $ sudo angie -t && sudo service angie reload ``` # https://en.angie.software/angie/docs/configuration/runtime.md # Runtime Control To start Angie, use **systemd** with the following command: ```console $ sudo service angie start ``` It is recommended to check the configuration syntax beforehand. Here is how: ```console $ sudo angie -t && sudo service angie start ``` To reload the configuration: ```console $ sudo angie -t && sudo service angie reload ``` To stop Angie: ```console $ sudo service angie stop ``` After installation, run the following command to ensure that Angie is up and running: ```console $ curl localhost:80 ``` #### NOTE The methods for running the open-source version of Angie may vary depending on the installation method. Angie has one master process and several worker processes. The master process is responsible for reading and evaluating the configuration and maintaining the worker processes. Worker processes handle the actual request processing. Angie uses an event-based model and OS-dependent mechanisms to efficiently distribute requests among the worker processes. The number of worker processes is defined in the configuration file and may be either fixed for a given configuration or automatically adjusted based on the number of available CPU cores (see [worker_processes](https://en.angie.software//angie/docs/configuration/modules/core.md#worker-processes)). When configured, Angie will also flush certain shared memory zones (currently, the `keys_zone` in [proxy_cache_path](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-path)) to disk before exiting, so the new master process can restore them and thereby improve performance. If the restore fails due to a change in zone size, binary version incompatibility, or other reasons, Angie will log a warning (`failed to restore zone at address`) and will not use the zone restore mechanism. ## Using Signals Angie can also be controlled using signals. By default, the process ID of the master process is written to the file `/run/angie.pid`. This filename can be changed at configuration time or in `angie.conf` using the [pid](https://en.angie.software//angie/docs/configuration/modules/core.md#pid) directive. The master process supports the following signals: | `TERM`, `INT` | Fast shutdown | |-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `QUIT` | [Graceful](https://en.angie.software//angie/docs/configuration/modules/core.md#worker-shutdown-timeout) shutdown | | `HUP` | Reload configuration, update time zone (only for FreeBSD and Linux),
start new worker processes with the updated configuration,
[gracefully](https://en.angie.software//angie/docs/configuration/modules/core.md#worker-shutdown-timeout) shut down old worker
processes | | `USR1` | Reopen log files | | `USR2` | Upgrade the executable file | | `WINCH` | [Graceful](https://en.angie.software//angie/docs/configuration/modules/core.md#worker-shutdown-timeout) shutdown of worker processes | You can send signals using **kill**: ```console $ sudo kill -QUIT $(cat /run/angie.pid) ``` Individual worker processes can also be controlled using signals, although this is optional. The supported signals are: | `TERM`, `INT` | Fast shutdown | |-----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `QUIT` | [Graceful](https://en.angie.software//angie/docs/configuration/modules/core.md#worker-shutdown-timeout) shutdown | | `USR1` | Reopen log files | | `WINCH` | Abnormal termination for debugging (requires [debug_points](https://en.angie.software//angie/docs/configuration/modules/core.md#debug-points) to be
enabled) | ## Changing Configuration In order for Angie to re-read the configuration file, a `HUP` signal should be sent to the master process. The master process first checks the syntax validity and then attempts to apply the new configuration, which includes opening new log files and listen sockets. If applying the new configuration fails, the master process rolls back the changes and continues operating with the old configuration. If the application succeeds, the master process starts new worker processes and sends messages to the old worker processes, requesting them to shut down [gracefully](https://en.angie.software//angie/docs/configuration/modules/core.md#worker-shutdown-timeout). The old worker processes close their listen sockets and continue to service existing clients. After all clients have been served, the old worker processes are shut down. Angie tracks configuration changes for each process. Generation numbers start at 1 when the server is first started. These numbers are incremented with each configuration reload and are visible in the process titles: ```console $ sudo angie $ ps aux | grep angie angie: master process v1.12.1 #1 [angie] angie: worker process #1 ``` After a successful configuration reload (regardless of whether there are actual changes), Angie increments the generation number for processes that received the new configuration: ```console $ sudo kill -HUP $(cat /run/angie.pid) $ ps aux | grep angie angie: master process v1.12.1 #2 [angie] angie: worker process #2 ``` If any worker processes from previous generations continue to operate, they will become immediately visible: ```console $ ps aux | grep angie angie: worker process #1 angie: worker process #2 ``` #### NOTE Do not confuse the configuration generation number with a 'process number'; Angie does not use continuous process numbering for practical purposes. ## Rotating Log Files To rotate log files, first rename the files. Then, send a `USR1` signal to the master process. The master process will re-open all currently open log files and assign them to an unprivileged user under which the worker processes are running. After successfully re-opening the files, the master process closes all open files and notifies the worker processes to re-open their log files. Worker processes will also open the new files and close the old ones immediately. As a result, the old files become available for post-processing, such as compression, almost immediately. ## On-the-fly Executable Upgrade To upgrade the server executable, first replace the old executable file with the new one. Then, send a `USR2` signal to the master process. The master process will rename its current file with the process ID to a new file with the `.oldbin` suffix, e.g., `/usr/local/angie/logs/angie.pid.oldbin`, and then start the new executable, which in turn starts new worker processes. Note that the old master process does not close its listen sockets and can be managed to restart its worker processes if necessary. If the new executable does not perform as expected, you can take one of the following actions: * Send the `HUP` signal to the old master process. This will start new worker processes without re-reading the configuration. You can then shut down all new processes [gracefully](https://en.angie.software//angie/docs/configuration/modules/core.md#worker-shutdown-timeout) by sending the `QUIT` signal to the new master process. * Send the `TERM` signal to the new master process. It will send a message to its worker processes, requesting them to exit immediately. If any processes do not exit, send the `KILL` signal to force them to exit. When the new master process exits, the old master process will automatically start new worker processes. If the new master process exits, the old master process will remove the `.oldbin` suffix from the file name with the process ID. If the upgrade is successful, send the `QUIT` signal to the old master process, and only the new processes will remain. When configured, Angie will also flush certain shared memory zones (currently, the `keys_zone` in [proxy_cache_path](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-path)) to disk before upgrading, so the new master process can restore them and thereby improve performance. If the restore fails due to a change in zone size, binary version incompatibility, or other reasons, Angie will log a warning (`failed to restore zone at address`) and will not use the zone restore mechanism. ## Command-Line Options | `-?`, `-h` | Display help for command-line parameters, then exit. | |-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `--build-env` | Display auxiliary information about the build environment, then exit. | | `-c` file | Use file as the configuration file instead of the [default file](https://en.angie.software//angie/docs/configuration/configfile.md#configfile). | | `-e` file | Use file as the error log file instead of the [default file](https://en.angie.software//angie/docs/configuration/processing.md#logging). The special value `stderr` specifies the standard error
output. | | `-g` directives | Set [global configuration directives](https://en.angie.software//angie/docs/configuration/modules/core.md#core),
for example: `angie -g "pid /var/run/angie.pid; worker_processes
`sysctl -n hw.ncpu`;"`. | | `-m`, `-M` | Display a list of built-in (`-m`) or built-in and loaded
(`-M`) modules, then exit. | | `-p` prefix | Use the specified prefix path for `angie` (the directory where server
files are located; the default is `/usr/local/angie/`). | | `-q` | Display only error messages if `-t` or `-T` is set;
otherwise, has no effect. | | `-s` signal | Send a [signal](#control-signals) to the master process:
`stop`, `quit`, `reopen`, `reload`, and so on. | | `-t` | Test the configuration file, then exit. Angie checks the
configuration syntax, recursively including files mentioned in it. | | `-T` | Same as `-t`, but also outputs the summary configuration to
standard output after recursively including all files mentioned in the
configuration. | | `-v` | Display the Angie version, then exit. | | `-V` | Display the Angie version, compiler version, build time
and the [build parameters](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure) used, then exit. | # https://en.angie.software/angie/docs/configuration/processing.md # Connections, Sessions, Requests, Logs ## Connection processing mechanisms Angie supports various connection processing methods. The availability of a specific method depends on the platform being used. On platforms that support multiple methods, Angie typically selects the most efficient method automatically. However, if necessary, a connection processing method can be explicitly chosen using the [use](https://en.angie.software//angie/docs/configuration/modules/core.md#use) directive. The following connection processing methods are available: | Method | Description | |-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `select` | A standard method. The supporting module is built automatically on
platforms that do not have more efficient methods. The
`--with-select_module` and `--without-select_module` build
options can be used to forcibly enable or disable the building of this
module. | | `poll` | A standard method. The supporting module is built automatically on
platforms that do not have more efficient methods. The
`--with-poll_module` and `--without-poll_module` build
options can be used to forcibly enable or disable the building of this
module. | | `kqueue` | An efficient method available on FreeBSD 4.1+, OpenBSD 2.9+, NetBSD 2.0,
and macOS. | | `epoll` | An efficient method available on Linux 2.6+. | | `/dev/poll` | An efficient method available on Solaris 7 11/99+, HP/UX 11.22+
(eventport), IRIX 6.5.15+, and Tru64 UNIX 5.1A+. | | `eventport` | The `event ports` method is available on Solaris 10+. (Due to known
issues, using the `/dev/poll` method is recommended instead.) | ## HTTP request processing An HTTP request goes through a series of phases, where a specific type of processing is performed at each phase. | `Post-read` | The initial phase. The [RealIP](https://en.angie.software//angie/docs/configuration/modules/http/http_realip.md#http-realip) module is
invoked during this phase. | |------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `Server-rewrite` | The phase where directives from the [Rewrite](https://en.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#http-rewrite)
module, defined in a `server` block (but outside a `location`
block), are processed. | | `Find-config` | A special phase where a [location](https://en.angie.software//angie/docs/configuration/modules/http/index.md#location) is selected based on the request
URI. | | `Rewrite` | Similar to the `Server-rewrite` phase, but it applies to
[rewrite](https://en.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#id5) rules defined within the location block selected in the
previous phase. | | `Post-rewrite` | A special phase where the request is redirected to a new location, as in
the `Find-config` phase, if its URI was modified during the
`Rewrite` phase. | | `Preaccess` | During this phase, standard Angie modules like [Limit Req](https://en.angie.software//angie/docs/configuration/modules/http/http_limit_req.md#http-limit-req) register their handlers. | | `Access` | The phase where the client's authorization to make the request is
verified, typically by invoking standard Angie modules such as
[Auth Basic](https://en.angie.software//angie/docs/configuration/modules/http/http_auth_basic.md#http-auth-basic). | | `Post-access` | A special phase where the [satisfy any](https://en.angie.software//angie/docs/configuration/modules/http/index.md#satisfy) directive is
processed. | | `Precontent` | Standard module directives, such as [try_files](https://en.angie.software//angie/docs/configuration/modules/http/index.md#try-files) and
[mirror](https://en.angie.software//angie/docs/configuration/modules/http/http_mirror.md#id1), register their handlers during this phase. | | `Content` | The phase where the response is usually generated.
Multiple standard Angie modules register their handlers at this stage,
including [Index](https://en.angie.software//angie/docs/configuration/modules/http/http_index.md#http-index).
The [proxy_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass), [fastcgi_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-pass),
[uwsgi_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-pass), [scgi_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-pass) and [grpc_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-pass) directives
are also handled here.

Handlers are called sequentially
until one of them produces the output. | | `Log` | The final phase, where request logging is performed. Currently, only the
[Log](https://en.angie.software//angie/docs/configuration/modules/http/http_log.md#http-log) module registers its handler at this stage
for access logging. | ## TCP/UDP session processing A TCP/UDP session from a client goes through a series of phases, where a specific type of processing is performed at each phase: | `Post-accept` | The initial phase after accepting a client connection. The [RealIP](https://en.angie.software//angie/docs/configuration/modules/stream/stream_realip.md#stream-realip) module is invoked at this phase. | |-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `Pre-access` | A preliminary phase for checking access. The [Set](https://en.angie.software//angie/docs/configuration/modules/stream/stream_set.md#stream-set) modules are invoked during this phase. | | `Access` | The phase for limiting client access before actual data processing. The
[Access](https://en.angie.software//angie/docs/configuration/modules/stream/stream_access.md#stream-access) module is invoked at this stage. | | `SSL` | The phase where TLS/SSL termination occurs. The [SSL](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#stream-ssl) module is invoked during this phase. | | `Preread` | The phase for reading initial bytes of data into the [preread buffer](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#s-preread-buffer-size) to allow modules such as [SSL Preread](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl_preread.md#stream-ssl-preread) to analyze the data before processing. | | `Content` | A mandatory phase where the data is actually processed, typically
involving the [Return](https://en.angie.software//angie/docs/configuration/modules/stream/stream_return.md#stream-return) module to send a
response to the client.
The [proxy_pass](https://en.angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-pass) directive is also handled here. | | `Log` | The final phase where the outcome of client session processing is
recorded. The [Log](https://en.angie.software//angie/docs/configuration/modules/stream/stream_log.md#stream-log) module is invoked at this
phase. | ## Processing requests ### Virtual server selection Initially, a connection is created within the context of a default server. The server name can then be determined in the following stages of request processing, each of which is involved in the selection of server configuration: - During the SSL handshake, in advance, according to the SNI. - After processing the request line. - After processing the `Host` header field. If the server name is not determined after processing the request line or the `Host` header field, Angie will use an empty name as the server name. At each of these stages, different server configurations may be applied. Therefore, certain directives should be specified with caution: - In the case of the [ssl_protocols](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-protocols) directive, the protocol list is set by the OpenSSL library before the server configuration is applied according to the name requested through SNI. As a result, protocols should only be specified for the default server. - The [client_header_buffer_size](https://en.angie.software//angie/docs/configuration/modules/http/index.md#client-header-buffer-size) and [merge_slashes](https://en.angie.software//angie/docs/configuration/modules/http/index.md#merge-slashes) directives are applied before reading the request line. Therefore, these directives use either the default server configuration or the server configuration chosen by SNI. - In the case of the [ignore_invalid_headers](https://en.angie.software//angie/docs/configuration/modules/http/index.md#ignore-invalid-headers), [large_client_header_buffers](https://en.angie.software//angie/docs/configuration/modules/http/index.md#large-client-header-buffers), and [underscores_in_headers](https://en.angie.software//angie/docs/configuration/modules/http/index.md#underscores-in-headers) directives, which are involved in processing request header fields, the server configuration additionally depends on whether it was updated according to the request line or the `Host` header field. - An error response is handled using the [error_page](https://en.angie.software//angie/docs/configuration/modules/http/index.md#error-page) directive in the server that is currently processing the request. ### Name-based virtual servers Angie first determines which server should handle the request. Consider a simple configuration where all three virtual servers listen on port 80: ```nginx server { listen 80; server_name example.org www.example.org; # ... } server { listen 80; server_name example.net www.example.net; # ... } server { listen 80; server_name example.com www.example.com; # ... } ``` In this configuration, Angie determines which server should handle the request based solely on the `Host` header field. If the value of this header does not match any server name or if the request does not contain this header field, Angie will route the request to the default server for this port. In the configuration above, the default server is the first one — which is Angie's standard default behavior. It can also be explicitly specified which server should be the default using the `default_server` parameter in the [listen](https://en.angie.software//angie/docs/configuration/modules/http/index.md#listen) directive: ```nginx server { listen 80 default_server; server_name example.net www.example.net; # ... } ``` #### NOTE Note that the default server is a property of the listen socket, not of the server name. ### Internationalized names Internationalized domain names ([IDNs](https://en.wikipedia.org/wiki/Internationalized_domain_name)) should be specified using an ASCII (Punycode) representation in the [server_name](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server-name) directive: ```nginx server { listen 80; server_name xn--e1afmkfd.xn--80akhbyknj4f; # пример.испытание # ... } ``` ### Preventing requests with undefined server names If requests without the `Host` header field should not be allowed, a server that simply drops such requests can be defined: ```nginx server { listen 80; server_name ""; return 444; } ``` In this configuration, the server name is set to an empty string, which matches requests without the `Host` header field. A special non-standard code 444 is then returned, which closes the connection. ### Combining name-based and IP-based virtual servers Let's examine a more complex configuration where some virtual servers listen on different addresses: ```nginx server { listen 192.168.1.1:80; server_name example.org www.example.org; # ... } server { listen 192.168.1.1:80; server_name example.net www.example.net; # ... } server { listen 192.168.1.2:80; server_name example.com www.example.com; # ... } ``` In this configuration, Angie first tests the IP address and port of the request against the [listen](https://en.angie.software//angie/docs/configuration/modules/http/index.md#listen) directives of the [server](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server) blocks. It then tests the `Host` header field of the request against the [server_name](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server-name) entries of the [server](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server) blocks that matched the IP address and port. If the server name is not found, the request will be processed by the default server. For example, a request for `www.example.com` received on port 192.168.1.1:80 will be handled by the default server for that port — i.e., by the first server — since `www.example.com` is not defined for this port. As previously mentioned, a default server is a property of the listen port, and different default servers may be defined for different ports: ```nginx server { listen 192.168.1.1:80; server_name example.org www.example.org; # ... } server { listen 192.168.1.1:80 default_server; server_name example.net www.example.net; # ... } server { listen 192.168.1.2:80 default_server; server_name example.com www.example.com; # ... } ``` ### Choosing locations Consider a simple PHP website configuration: ```nginx server { listen 80; server_name example.org www.example.org; root /data/www; location / { index index.html index.php; } location ~* \.(gif|jpg|png)$ { expires 30d; } location ~ \.php$ { fastcgi_pass localhost:9000; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; include fastcgi_params; } } ``` Angie first searches for the most specific prefix `location` given by literal strings, regardless of their listed order. In the configuration above, the only prefix location is `location /`, which matches any request and will be used as a last resort. Angie then checks locations defined by regular expressions in the order they appear in the configuration file. The first matching expression stops the search, and Angie will use that `location`. If no regular expression matches a request, Angie will use the most specific prefix `location` found earlier. #### NOTE Locations of all types test only the URI part of the request line, excluding arguments. This is because arguments in the query string can be specified in various ways, for example: - `/index.php?user=john&page=1` - `/index.php?page=1&user=john` Additionally, query strings may contain any number of parameters: - `/index.php?page=1&something+else&user=john` Now let's look at how requests would be processed in the configuration above: - The request `/logo.gif` is first matched by the prefix `location /` and then by the regular expression `.(gif|jpg|png)$`. Therefore, it is handled by the latter location. Using the directive `root /data/www`, the request is mapped to the file `/data/www/logo.gif`, and the file is sent to the client. - The request `/index.php` is also initially matched by the prefix `location /` and then by the regular expression `.(php)$`. Consequently, it is handled by the latter location, and the request is passed to a FastCGI server listening on `localhost:9000`. The [fastcgi_param](https://en.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-param) directive sets the FastCGI parameter `SCRIPT_FILENAME` to `/data/www/index.php`, and the FastCGI server executes the file. The variable [$document_root](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-document-root) is set to the value of the `root` directive, and the variable [$fastcgi_script_name](https://en.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#v-fastcgi-script-name) is set to the request URI, i.e., `/index.php`. - The request `/about.html` is matched only by the prefix `location /`, so it is handled in this location. Using the directive `root /data/www`, the request is mapped to the file `/data/www/about.html`, and the file is sent to the client. Handling the request `/` is more complex. It is matched only by the prefix `location /`, so it is handled by this location. The [index](https://en.angie.software//angie/docs/configuration/modules/http/http_index.md#id1) directive then tests for the existence of index files according to its parameters and the `root /data/www` directive. If the file `/data/www/index.html` does not exist but the file `/data/www/index.php` does, the directive performs an internal redirect to `/index.php`, and Angie searches the locations again as if the request had been sent by a client. As previously mentioned, the redirected request will eventually be handled by the FastCGI server. The examples above map a request to a file through the [root](https://en.angie.software//angie/docs/configuration/modules/http/index.md#root) directive, but the full mapping involves several directives acting together. Once a matching [location](https://en.angie.software//angie/docs/configuration/modules/http/index.md#location) is selected, Angie maps the normalized [$uri](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-uri) of the request to a filesystem path: the [root](https://en.angie.software//angie/docs/configuration/modules/http/index.md#root) directive appends the whole URI to its value, whereas the [alias](https://en.angie.software//angie/docs/configuration/modules/http/index.md#alias) directive replaces the matched location prefix. The [try_files](https://en.angie.software//angie/docs/configuration/modules/http/index.md#try-files) directive then probes for candidate files relative to that path; if none exist, its last parameter triggers an internal redirect, and Angie searches the locations again against the new [$uri](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-uri), just as with the index redirect above. For the same request `/images/top.gif`, the two locations below resolve it to the same file, `/data/w3/images/top.gif`: ```nginx location /images/ { root /data/w3; # append: /data/w3 + /images/top.gif } location /images/ { alias /data/w3/images/; # replace: /images/ -> /data/w3/images/, then top.gif } ``` With [alias](https://en.angie.software//angie/docs/configuration/modules/http/index.md#alias), the matched prefix is removed by its length, so the trailing slashes of the location and of the alias value must be consistent. Dropping the trailing slash from the alias path above would instead yield `/data/w3/imagestop.gif`. ## Proxying and Load Balancing One common use of Angie is to set it up as a proxy server. In this role, Angie receives requests, forwards them to the proxied servers, retrieves responses from those servers, and sends the responses back to the clients. A simple proxy server: ```nginx server { location / { proxy_pass http://backend:8080; } ``` The [proxy_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass) directive instructs Angie to pass client requests to the backend `backend:8080` (the proxied server). There are many additional [directives](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy) available for further configuring a proxy connection. ### FastCGI Proxying Angie can be used to route requests to FastCGI servers that run applications built with various frameworks and programming languages, such as PHP. The most basic Angie configuration for working with a FastCGI server involves using the [fastcgi_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-pass) directive instead of the [proxy_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass) directive, along with [fastcgi_param](https://en.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-param) directives to set parameters passed to the FastCGI server. Suppose the FastCGI server is accessible on `localhost:9000`. In PHP, the `SCRIPT_FILENAME` parameter is used to determine the script name, and the `QUERY_STRING` parameter is used to pass request parameters. The resulting configuration would be: ```nginx server { location / { fastcgi_pass localhost:9000; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; fastcgi_param QUERY_STRING $query_string; } location ~ \.(gif|jpg|png)$ { root /data/images; } } ``` This configuration sets up a server that routes all requests, except those for static images, to the proxied server operating on `localhost:9000` via the FastCGI protocol. ### WebSocket Proxying To upgrade a connection from HTTP/1.1 to WebSocket, the [protocol switch](https://datatracker.ietf.org/doc/html/rfc2616#section-14.42) mechanism available in HTTP/1.1 is used. However, there is a subtlety: since the `Upgrade` header is a [hop-by-hop header](https://datatracker.ietf.org/doc/html/rfc2616#section-13.5.1), it is not passed from the client to the proxied server. With forward proxying, clients may use the CONNECT method to circumvent this issue. This approach does not work with reverse proxying, as clients are unaware of any proxy servers, and special processing on the proxy server is required. Angie implements a special mode of operation that allows setting up a tunnel between a client and a proxied server if the proxied server returns a response with code 101 (Switching Protocols), and the client requests a protocol switch via the `Upgrade` header in the request. As mentioned, hop-by-hop headers, including `Upgrade` and `Connection`, are not passed from the client to the proxied server. Therefore, for the proxied server to be aware of the client's intention to switch to the WebSocket protocol, these headers must be explicitly passed: ```nginx location /chat/ { proxy_pass http://backend; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; } ``` A more sophisticated example demonstrates how the value of the `Connection` header field in a request to the proxied server depends on the presence of the `Upgrade` field in the client request header: ```nginx http { map $http_upgrade $connection_upgrade { default upgrade; '' close; } server { ... location /chat/ { proxy_pass http://backend; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade; } } } ``` By default, the connection will be closed if the proxied server does not transmit any data within 60 seconds. This timeout can be increased using the [proxy_read_timeout](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-read-timeout) directive. Alternatively, the proxied server can be configured to periodically send WebSocket ping frames to reset the timeout and check if the connection is still active. ### Load Balancing Load balancing across multiple application instances is a widely used technique to optimize resource utilization, maximize throughput, reduce latency, and ensure fault-tolerant configurations. Angie can be used as a highly efficient HTTP load balancer to distribute traffic to multiple application servers, thereby enhancing the performance, scalability, and reliability of web applications. The simplest configuration for load balancing with Angie might look like this: ```nginx http { upstream myapp1 { server srv1.example.com; server srv2.example.com; server srv3.example.com; } server { listen 80; location / { proxy_pass http://myapp1; } } } ``` In the example above, three instances of the same application are running on `srv1` through `srv3`. When a load balancing method is not explicitly configured, it defaults to round-robin. Other supported load balancing mechanisms include: [weight](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server), [least_conn](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-least-conn), and [ip_hash](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-ip-hash). The reverse proxy implementation in Angie also supports in-band (or passive) server health probes. These are configured using the [max_fails](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) and [fail_timeout](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#fail-timeout) directives within the [server](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) block in the [upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) context. ## Logging #### NOTE In addition to the options listed here, you can also enable the [debugging log](https://en.angie.software//angie/docs/troubleshooting.md#debug-logging). ### Syslog The [error_log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log) and [access_log](https://en.angie.software//angie/docs/configuration/modules/http/http_log.md#access-log) directives support logging to `syslog`. The following parameters are used to configure logging to `syslog`: | `server=`address | Specifies the address of a `syslog` server. The address can be a
domain name or an IP address, with an optional port, or a UNIX domain
socket path specified after the `"unix:"` prefix. If the port is
not specified, UDP port 514 is used. If a domain name resolves to
multiple IP addresses, the first resolved address is used. | |--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `facility=`string | Sets the facility for `syslog` messages, as defined in [RFC 3164](https://datatracker.ietf.org/doc/html/rfc3164.html). Possible
facilities include: `"kern"`, `"user"`, `"mail"`,
`"daemon"`, `"auth"`, `"intern"`, `"lpr"`,
`"news"`, `"uucp"`, `"clock"`, `"authpriv"`,
`"ftp"`, `"ntp"`, `"audit"`, `"alert"`,
`"cron"`, `"local0".."local7"`. The default is
`"local7"`. | | `severity=`string | Defines the severity level of `syslog` messages for
[access_log](https://en.angie.software//angie/docs/configuration/modules/http/http_log.md#access-log), as specified in [RFC 3164](https://datatracker.ietf.org/doc/html/rfc3164.html). Possible values
are the same as those for the second parameter (level) of the
[error_log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log) directive. The default is `"info"`. The severity
of error messages is determined by Angie, so this parameter is
ignored in the [error_log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log) directive. | | `tag=`string | Sets the tag for `syslog` messages. The default tag is
`"angie"`. | | `nohostname` | Disables the addition of the `hostname` field in the `syslog`
message header. | Example syslog configuration: ```nginx error_log syslog:server=192.168.1.1 debug; access_log syslog:server=unix:/var/log/angie.sock,nohostname; access_log syslog:server=[2001:db8::1]:12345,facility=local7,tag=angie,severity=info combined; ``` # https://en.angie.software/angie/docs/configuration/modules.md # Modules This guide describes Angie's modules, both native and third-party, provides configuration examples, lists their directives and parameters, as well as built-in variables. ## Core Module | [Core](https://en.angie.software//angie/docs/configuration/modules/core.md#core) | Management of service files, processes, and other Angie modules. | |------------------------------------------------------------------------------------|--------------------------------------------------------------------| ## HTTP Modules | [HTTP](https://en.angie.software//angie/docs/configuration/modules/http/index.md#http-core) | Core functionality for processing HTTP requests and responses,
managing the HTTP server, connections, and static files. | |----------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------| | [Access](https://en.angie.software//angie/docs/configuration/modules/http/http_access.md#http-access) | Access control based on IP addresses and CIDR ranges. | | [ACME](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme) | Automatic retrieval and renewal of SSL certificates
using the ACME protocol for HTTP servers. | | [Docker](https://en.angie.software//angie/docs/configuration/modules/http/http_docker.md#http-docker) | Dynamic updating of proxied server groups
based on Docker container labels. | | [Addition](https://en.angie.software//angie/docs/configuration/modules/http/http_addition.md#http-addition) | Insertion of a specified snippet before or after the response body. | | [API](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#http-api) | RESTful HTTP interface for obtaining basic web server information and
statistics in JSON format,
as well as managing groups of proxied servers. | | [Auth Basic](https://en.angie.software//angie/docs/configuration/modules/http/http_auth_basic.md#http-auth-basic) | Basic HTTP authentication for access control
based on username and password. | | [Auth Request](https://en.angie.software//angie/docs/configuration/modules/http/http_auth_request.md#http-auth-request) | Authorization using a subrequest to an external HTTP service. | | [AutoIndex](https://en.angie.software//angie/docs/configuration/modules/http/http_autoindex.md#http-autoindex) | Automatic directory listing without an index file. | | [Browser](https://en.angie.software//angie/docs/configuration/modules/http/http_browser.md#http-browser) (deprecated) | Browser identification based on the `User-Agent` header. | | [Charset](https://en.angie.software//angie/docs/configuration/modules/http/http_charset.md#http-charset) | Configuration and conversion of response encoding. | | [DAV](https://en.angie.software//angie/docs/configuration/modules/http/http_dav.md#http-dav) | File management on the server using the WebDAV protocol. | | [DoH](https://en.angie.software//angie/docs/configuration/modules/http/http_doh.md#http-doh) | DNS over HTTPS (RFC 8484) server that proxies DNS queries
to a group of DNS servers over UDP or TCP. | | [Empty GIF](https://en.angie.software//angie/docs/configuration/modules/http/http_empty_gif.md#http-empty-gif) | Serving a one-pixel transparent GIF. | | [FastCGI](https://en.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#http-fastcgi) | Proxying requests to a FastCGI server. | | [FLV](https://en.angie.software//angie/docs/configuration/modules/http/http_flv.md#http-flv) | Pseudo-streaming of Flash Video (FLV) files. | | [Geo](https://en.angie.software//angie/docs/configuration/modules/http/http_geo.md#http-geo) | Converting IP addresses into specified variable values. | | [GeoIP](https://en.angie.software//angie/docs/configuration/modules/http/http_geoip.md#http-geoip) | Obtaining IP address data
based on geolocation using MaxMind GeoIP databases. | | [gRPC](https://en.angie.software//angie/docs/configuration/modules/http/http_grpc.md#http-grpc) | Proxying requests to a gRPC server. | | [GunZIP](https://en.angie.software//angie/docs/configuration/modules/http/http_gunzip.md#http-gunzip) | Decompressing GZip-compressed responses for modification and in cases
where the client does not support compression. | | [GZip](https://en.angie.software//angie/docs/configuration/modules/http/http_gzip.md#http-gzip) | Compressing responses using the GZip method to save traffic. | | [GZip Static](https://en.angie.software//angie/docs/configuration/modules/http/http_gzip_static.md#http-gzip-static) | Serving static files pre-compressed using the GZip method. | | [Headers](https://en.angie.software//angie/docs/configuration/modules/http/http_headers.md#http-headers) | Modifying response header fields. | | [HTTP/2](https://en.angie.software//angie/docs/configuration/modules/http/http_v2.md#http-v2) | Processing requests using the HTTP/2 protocol. | | [HTTP/3](https://en.angie.software//angie/docs/configuration/modules/http/http_v3.md#http-v3) | Processing requests using the HTTP/3 protocol. | | [Image Filter](https://en.angie.software//angie/docs/configuration/modules/http/http_image_filter.md#http-image-filter) ^[1](#id8) | Image transformation. | | [Index](https://en.angie.software//angie/docs/configuration/modules/http/http_index.md#http-index) | Configuration of index files
that serve requests ending with a slash (`/`). | | [Limit Conn](https://en.angie.software//angie/docs/configuration/modules/http/http_limit_conn.md#http-limit-conn) | Limiting the number of concurrent requests (active connections)
for protection against overload. | | [Limit Req](https://en.angie.software//angie/docs/configuration/modules/http/http_limit_req.md#http-limit-req) | Limiting request frequency
for protection against overload and password guessing. | | [Log](https://en.angie.software//angie/docs/configuration/modules/http/http_log.md#http-log) | Configuration of request logs for tracking resource access
for monitoring and analysis purposes. | | [Map](https://en.angie.software//angie/docs/configuration/modules/http/http_map.md#http-map) | Converting variables based on predefined key-value pairs. | | [Metric](https://en.angie.software//angie/docs/configuration/modules/http/http_metric.md#http-metric) | Custom numeric metrics in the real-time statistics API. | | [Memcached](https://en.angie.software//angie/docs/configuration/modules/http/http_memcached.md#http-memcached) | Retrieving responses from a Memcached server. | | [Mirror](https://en.angie.software//angie/docs/configuration/modules/http/http_mirror.md#http-mirror) | Mirroring requests to other servers. | | [MP4](https://en.angie.software//angie/docs/configuration/modules/http/http_mp4.md#http-mp4) | Pseudo-streaming of MP4 files. | | [Perl](https://en.angie.software//angie/docs/configuration/modules/http/http_perl.md#http-perl) ^[1](#id8) | Handlers for extending functionality
by specifying additional logic in the Perl language. | | [Prometheus](https://en.angie.software//angie/docs/configuration/modules/http/http_prometheus.md#http-prometheus) | Server metrics in Prometheus-compatible format
for monitoring and statistics collection. | | [Proxy](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy) | Reverse proxying requests to other HTTP servers. | | [Random Index](https://en.angie.software//angie/docs/configuration/modules/http/http_random_index.md#http-random-index) | Random selection of an index file for requests
ending with a slash (`/`). | | [RealIP](https://en.angie.software//angie/docs/configuration/modules/http/http_realip.md#http-realip) | Determining client address and port
when operating behind another proxy server. | | [Referer](https://en.angie.software//angie/docs/configuration/modules/http/http_referer.md#http-referer) | Validation of `Referer` header values. | | [Rewrite](https://en.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#http-rewrite) | Request URI modification, redirects, variable setting,
and conditional configuration selection. | | [SCGI](https://en.angie.software//angie/docs/configuration/modules/http/http_scgi.md#http-scgi) | Proxying requests to an SCGI server. | | [Secure Link](https://en.angie.software//angie/docs/configuration/modules/http/http_secure_link.md#http-secure-link) | Creating secure links with the ability to limit access time. | | [Slice](https://en.angie.software//angie/docs/configuration/modules/http/http_slice.md#http-slice) | Splitting requests into multiple subrequests for individual fragments
for better caching of large responses. | | [Split Clients](https://en.angie.software//angie/docs/configuration/modules/http/http_split_clients.md#http-split-clients) | Creating variables for A/B testing, canary releases, sharding,
and other scenarios requiring proportional group splitting. | | [SSI](https://en.angie.software//angie/docs/configuration/modules/http/http_ssi.md#http-ssi) | Processing SSI (Server Side Includes) commands in responses. | | [SSL](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#http-ssl) | SSL/TLS configuration for processing HTTPS requests. | | [Stub Status](https://en.angie.software//angie/docs/configuration/modules/http/http_stub_status.md#http-stub-status) (deprecated) | Global connection and request counters in text format. | | [Sub](https://en.angie.software//angie/docs/configuration/modules/http/http_sub.md#http-sub) | Search and replace fragments in the response body. | | [Tunnel](https://en.angie.software//angie/docs/configuration/modules/http/http_tunnel.md#http-tunnel) | Handling HTTP/1.1 CONNECT requests and establishing end-to-end tunnels. | | [Upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream) | Configuration of proxied server groups for load balancing. | | [Upstream Probe](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#http-upstream-probe) | Configuration of active health probes
for proxied server groups. | | [UserID](https://en.angie.software//angie/docs/configuration/modules/http/http_userid.md#http-userid) | Issuing and processing cookies with unique client identifiers
for session tracking and analytics. | | [uWSGI](https://en.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#http-uwsgi) | Proxying requests to a uWSGI server. | | [XSLT](https://en.angie.software//angie/docs/configuration/modules/http/http_xslt.md#http-xslt) ^[1](#id8) | Transforming XML documents using the XSLT language. | ## Stream Modules | [Stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) | Core stream server functionality
for balancing TCP and UDP protocols at the L4 level. | |-------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------| | [Access](https://en.angie.software//angie/docs/configuration/modules/stream/stream_access.md#stream-access) | Access control based on IP addresses and CIDR ranges. | | [ACME](https://en.angie.software//angie/docs/configuration/modules/stream/stream_acme.md#stream-acme) | Automatic retrieval and renewal of SSL certificates
using the ACME protocol for stream servers. | | [Geo](https://en.angie.software//angie/docs/configuration/modules/stream/stream_geo.md#stream-geo) | Converting IP addresses into specified variable values. | | [GeoIP](https://en.angie.software//angie/docs/configuration/modules/stream/stream_geoip.md#stream-geoip) | Obtaining IP address data
based on geolocation using MaxMind GeoIP databases. | | [Limit Conn](https://en.angie.software//angie/docs/configuration/modules/stream/stream_limit_conn.md#stream-limit-conn) | Limiting the number of concurrent connections
for protection against overload. | | [Log](https://en.angie.software//angie/docs/configuration/modules/stream/stream_log.md#stream-log) | Configuration of session logs for tracking resource access
for monitoring and analysis purposes. | | [Map](https://en.angie.software//angie/docs/configuration/modules/stream/stream_map.md#stream-map) | Converting variables based on predefined key-value pairs. | | [Metric](https://en.angie.software//angie/docs/configuration/modules/stream/stream_metric.md#stream-metric) | Custom numeric metrics in the real-time statistics API. | | [MQTT Preread](https://en.angie.software//angie/docs/configuration/modules/stream/stream_mqtt_preread.md#stream-mqtt-preread) | Reading client identifier and username from MQTT connections
before making load balancing decisions. | | [Pass](https://en.angie.software//angie/docs/configuration/modules/stream/stream_pass.md#stream-pass) | Passing accepted connections
directly to a configured listening socket. | | [Proxy](https://en.angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#stream-proxy) | Configuration of proxying to other servers. | | [RDP Preread](https://en.angie.software//angie/docs/configuration/modules/stream/stream_rdp_preread.md#stream-rdp-preread) | Reading cookies from RDP connections
before making load balancing decisions. | | [RealIP](https://en.angie.software//angie/docs/configuration/modules/stream/stream_realip.md#stream-realip) | Determining client address and port
when operating behind another proxy server. | | [Return](https://en.angie.software//angie/docs/configuration/modules/stream/stream_return.md#stream-return) | Sending a specified value to the client upon connection
without further proxying. | | [Set](https://en.angie.software//angie/docs/configuration/modules/stream/stream_set.md#stream-set) | Setting specified variable values. | | [Split Clients](https://en.angie.software//angie/docs/configuration/modules/stream/stream_split_clients.md#stream-split-clients) | Creating variables for A/B testing, canary releases, sharding,
and other scenarios requiring proportional group splitting. | | [SSL](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#stream-ssl) | SSL/TLS and DTLS protocol termination. | | [SSL Preread](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl_preread.md#stream-ssl-preread) | Extracting information from `ClientHello` messages without SSL/TLS termination
and before making load balancing decisions. | | [Upstream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#stream-upstream) | Configuration of proxied server groups for load balancing. | | [Upstream Probe](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#stream-upstream-probe) | Configuration of active health probes
for proxied server groups. | ## Mail Modules | [Mail](https://en.angie.software//angie/docs/configuration/modules/mail/index.md#mail-core) | Core mail proxy server functionality. | |----------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------| | [Auth HTTP](https://en.angie.software//angie/docs/configuration/modules/mail/mail_auth_http.md#mail-auth-http) | User authentication and server selection for subsequent
proxying using HTTP requests to an external server. | | [IMAP](https://en.angie.software//angie/docs/configuration/modules/mail/mail_imap.md#mail-imap) | IMAP protocol support. | | [POP3](https://en.angie.software//angie/docs/configuration/modules/mail/mail_pop3.md#mail-pop3) | POP3 protocol support. | | [Proxy](https://en.angie.software//angie/docs/configuration/modules/mail/mail_proxy.md#mail-proxy) | Configuration of proxying to other servers. | | [RealIP](https://en.angie.software//angie/docs/configuration/modules/mail/mail_realip.md#mail-realip) | Determining client address and port
when operating behind another proxy server. | | [SMTP](https://en.angie.software//angie/docs/configuration/modules/mail/mail_smtp.md#mail-smtp) | SMTP protocol support. | | [SSL](https://en.angie.software//angie/docs/configuration/modules/mail/mail_ssl.md#mail-ssl) | SSL/TLS and StartTLS protocol support. | ## Google PerfTools Module | [Google PerfTools](https://en.angie.software//angie/docs/configuration/modules/google_perftools.md#google-perftools) | Responsible for integration with the Google Performance Tools library for
application profiling and performance analysis. | |------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------| ## WASM Modules | [WASM](https://en.angie.software//angie/docs/configuration/modules/wasm/index.md#wasm-core) ^[1](#id8) | Core WASM functionality enabling WASM code execution in Angie. | |--------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------| | [WAMR](https://en.angie.software//angie/docs/configuration/modules/wasm/wasm_wamr.md#wasm-wamr) | Integration with
[WebAssembly Micro Runtime](https://github.com/bytecodealliance/wasm-micro-runtime). | | [Wasmtime](https://en.angie.software//angie/docs/configuration/modules/wasm/wasm_wasmtime.md#wasm-wasmtime) | Integration with the [Wasmtime](https://wasmtime.dev/) runtime environment. | ## Third-party Modules Third-party nginx-compatible modules for which we build packages. The full annotated list with brief descriptions is in the [Third-Party Modules](https://en.angie.software//angie/docs/configuration/modules/external-modules/index.md#list-of-modules) section. ### Footnotes * **[1]** In our builds, these modules are compiled dynamically and installed as [separate packages](https://en.angie.software//angie/docs/installation/index.md#install-packages); for details, see the description of each module. # https://en.angie.software/angie/docs/configuration/modules/core.md # Core Module The module provides essential functionality and configuration directives necessary for the basic operation of the server, and handles critical tasks such as managing worker processes, configuring event-driven models, and processing incoming connections and requests. It includes key directives for setting up the main process, error logging, and controlling the behavior of the server at a low level. ## Configuration Example ```nginx user www www; worker_processes 2; error_log /var/log/error.log info; events { use kqueue; worker_connections 2048; } ``` ## Directives ### accept_mutex | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `accept_mutex` `on` | `off`; | |------------------------------------------------------------------------------------------|--------------------------------| | Default | `accept_mutex off;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | events | When `accept_mutex` is enabled, worker processes will accept new connections in turn. Without this setting, all worker processes are notified of new connections, which can lead to inefficient use of system resources if the volume of new connections is low. #### NOTE There is no need to enable `accept_mutex` on systems that support the `EPOLLEXCLUSIVE` flag or when using the [reuseport](https://en.angie.software//angie/docs/configuration/modules/http/index.md#listen) directive. ### accept_mutex_delay | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `accept_mutex_delay` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units); | |------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------| | Default | `accept_mutex_delay 500ms;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | events | If [accept_mutex](#accept-mutex) is enabled, this directive specifies the maximum time a worker process will wait to continue accepting new connections while another worker process is already handling new connections. ### daemon | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `daemon` `on` | `off`; | |------------------------------------------------------------------------------------------|--------------------------| | Default | `daemon on;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | main | Determines whether Angie should run as a daemon. This is primarily used during development. ### debug_connection | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `debug_connection` address | CIDR | `unix:`; | |------------------------------------------------------------------------------------------|------------------------------------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | events | Enables debugging logs for specific client connections. Other connections will use the logging level set by the [error_log](#error-log) directive. You can specify connections by IPv4 or IPv6 address, network, or hostname. For connections using UNIX domain sockets, use the `unix:` parameter to enable debugging logs. ```nginx events { debug_connection 127.0.0.1; debug_connection localhost; debug_connection 192.0.2.0/24; debug_connection ::1; debug_connection 2001:0db8::/32; debug_connection unix:; # ... } ``` #### NOTE For this directive to work, Angie must be built with [debugging log](https://en.angie.software//angie/docs/troubleshooting.md#debug-logging) enabled. ### debug_points | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `debug_points` `abort` | `stop`; | |------------------------------------------------------------------------------------------|------------------------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | main | This directive is used for debugging. When an internal error occurs, such as a socket leak during worker process restarts, enabling `debug_points` will either create a core file (`abort`) or stop the process (`stop`) for further analysis with a system debugger. ### env | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `env` variable[=value]; | |------------------------------------------------------------------------------------------|---------------------------| | Default | `env TZ;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | main | By default, Angie removes all environment variables inherited from its parent process except for the `TZ` variable. This directive allows you to preserve some inherited variables, modify their values, or create new environment variables. These variables are then: - inherited during a [live upgrade of an executable file](https://en.angie.software//angie/docs/configuration/runtime.md#service-upgrade) - used by the [Perl](https://en.angie.software//angie/docs/configuration/modules/http/http_perl.md#http-perl) module - available to worker processes Note that controlling system libraries in this way may not always be effective, as libraries often check variables only during initialization, which occurs before this directive takes effect. The `TZ` variable is always inherited and accessible to the [Perl](https://en.angie.software//angie/docs/configuration/modules/http/http_perl.md#http-perl) module unless explicitly configured otherwise. Example: ```nginx env MALLOC_OPTIONS; env PERL5LIB=/data/site/modules; env OPENSSL_ALLOW_PROXY_CERTS=1; ``` #### NOTE The `ANGIE` environment variable is used internally by Angie and should not be set directly by the user. ### error_log #### Versionchanged Changed in version 1.12.0. | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `error_log` file [level] [[`filter=`part:match] ...] [`rate=`rate] [`format=`format]; | |------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Default | `error_log logs/error.log error;`
(the path depends on the `--error-log-path` [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#paths)) | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | main, http, mail, stream, server, location | Configures logging, allowing multiple logs to be specified at the same configuration level. If a log file is not explicitly defined at the `main` configuration level, the default file will be used. The first parameter specifies the file to store the log. The special value `stderr` selects the standard error stream. To configure logging to [syslog](https://en.angie.software//angie/docs/configuration/processing.md#syslog-logging), use the `"syslog:"` prefix. To log to a [cyclic memory buffer](https://en.angie.software//angie/docs/troubleshooting.md#cyclic-memory-buffer), use the `"memory:"` prefix followed by the buffer size; this is typically used for debugging. The second parameter sets the logging level, which can be one of the following: `debug`, `info`, `notice`, `warn`, `error`, `crit`, `alert`, or `emerg`. These levels are listed in order of increasing severity. Setting a log level will capture messages of equal and higher severity: | Setting | Levels Captured | |-----------|--------------------------------------------------------------------------| | `debug` | `debug`, `info`, `notice`, `warn`, `error`,
`crit`, `alert`, `emerg` | | `info` | `info`, `notice`, `warn`, `error`,
`crit`, `alert`, `emerg` | | `notice` | `notice`, `warn`, `error`,
`crit`, `alert`, `emerg` | | `warn` | `warn`, `error`, `crit`, `alert`, `emerg` | | `error` | `error`, `crit`, `alert`, `emerg` | | `crit` | `crit`, `alert`, `emerg` | | `alert` | `alert`, `emerg` | | `emerg` | `emerg` | If this parameter is omitted, `error` is used as the default logging level. Optional `filter=`part:match parameters restrict which messages are written to the log, so a single destination can collect only the events of interest. Each parameter tests one part of the message against the match pattern, where part is one of: - `logline` — with `format=default`, the message together with any system error and context details, but without the timestamp, level, process, thread, and connection prefix; it does not match entries with `format=json`; - `message` — with `format=default`, the message text without system error or context details; with `format=json`, the escaped, serialized fragment containing the `message` member rather than its raw value; - `tag` — a tag attached to the message, including tags added by the [error_log_user_tag](https://en.angie.software//angie/docs/configuration/modules/http/index.md#error-log-user-tag) directive and its [stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#s-error-log-user-tag) and [mail](https://en.angie.software//angie/docs/configuration/modules/mail/index.md#m-error-log-user-tag) counterparts; - `sourcefile` — the source file that emitted the message; available only when Angie is built with the [debugging log](https://en.angie.software//angie/docs/troubleshooting.md#debug-logging) enabled; - any other name — a field of the message context, such as one of the fields shown in the JSON format below. By default the match pattern is matched as a substring. Prefix it with `=` to require an exact match, or with `~` to match a regular expression, which requires a build with the PCRE library. With `format=json`, an exact `message` match must cover the entire serialized fragment, including its JSON syntax and escaping. Several `filter=` parameters may be given for one directive; a message is written only when it matches all of them. Optional `rate=`rate parameter limits the maximum rate of messages written to the log, in messages per second; the value may end with the `m/s` suffix (for example, `rate=2000m/s`). By default, `rate=1000` (1000 messages per second) is used; set `rate=0` to disable the limit. The limit is applied separately to each `error_log` directive and independently in each worker process. A flood of low-severity messages (for example `info`) does not suppress higher-severity ones such as `error`, because more severe levels are allowed a proportionally larger burst; the reverse is not true. Excess messages are dropped. This throttles the log rather than muting it: under sustained overload, messages are still written at approximately the configured rate. When a rate-limited destination is not the head of the effective error-log chain, the first dropped message also produces a "too many log messages, limiting" notice at the same level. The notice can recur during sustained overload. It is suppressed for the chain head, including when that is the only destination. Rate limiting doesn't apply when the `debug` logging level is in effect for a message — either because the log file itself uses the `debug` level, or because debugging logs are enabled for the connection via [debug_connection](#debug-connection). #### NOTE For the `debug` logging level to work, Angie must be built with [debugging log](https://en.angie.software//angie/docs/troubleshooting.md#debug-logging) enabled. Optional `format=`format parameter selects the format used for log entries. The default, `format=default`, produces the traditional plain-text format described below; `format=json` writes each entry as a single JSON object on one line. In the default format, each entry in the error log has the following format: ```text timestamp [level] PID#TID: *connection_id message ``` Where: - `timestamp` — date and time of the event - `level` — logging level of the event - `PID#TID` — process and thread identifiers - `*connection_id` — connection serial number, shared by all requests on the same connection (if applicable) - `message` — error or event message text With `format=json`, each entry is instead written as a single JSON object, shown here pretty-printed for readability; in the log file it occupies a single line: ```json { "time": "2026-02-14T09:23:10.874Z", "level": "error", "pid": 22738, "tid": 22738, "connection": 7, "message": "limiting requests, excess: 1.000 by zone \"one\"", "http": { "client": "127.0.0.1", "request": { "server": "localhost", "request_line": "GET /debug HTTP/1.1", "host": "localhost" } }, "tags": [ "http" ] } ``` Where: - `time` — date and time of the event, in ISO 8601 format - `level` — logging level of the event - `pid` and `tid` — process and thread identifiers - `connection` — connection number (the same value shown as `*connection_id` in the plain-text format), present when the entry is associated with a connection - `message` — error or event message text - `error` — present when the message is associated with a system error; an object with `code` and `message` fields - `http`, `stream`, or `mail` — an object with the entry's context details, keyed by the name of the module where the entry originated (a generic `context` object is used for context details outside these modules); the object only appears for entries that carry such details and are logged at a level other than `debug`. Each module's object has its own set of fields; for example, under `http` a nested `request` object holds `request_line`, the request line, along with other request details - `tags` — list of tags attached to the entry, present when at least one tag applies; includes tags added automatically by modules and by [error_log_user_tag](https://en.angie.software//angie/docs/configuration/modules/http/index.md#error-log-user-tag) directives - `truncated` — `true`, present only when the entry had to be truncated to fit the error log buffer ### events | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `events` { ... }; | |------------------------------------------------------------------------------------------|---------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | main | Provides the configuration file context for directives that affect connection processing. ### include | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `include` file | mask; | |------------------------------------------------------------------------------------------|--------------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | any | Includes another file, or files that match the specified mask, into the configuration. The included files must contain syntactically correct directives and blocks. Example: ```nginx include mime.types; include vhosts/*.conf; ``` ### load_module | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `load_module` file; | |------------------------------------------------------------------------------------------|-----------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | main | Loads a dynamic module from the specified file. If a relative path is provided, it is interpreted based on the `--prefix` [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure). To verify the path: ```console $ sudo angie -V ``` Example: ```nginx load_module modules/ngx_mail_module.so; ``` If a dynamic module was built for a different Angie build, loading fails with an error like: "module "..." was built for "..." but you are running "Angie"". ### lock_file | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `lock_file` file; | |------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Default | `lock_file logs/angie.lock;`
(the path depends on the `--lock-path` [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#paths)) | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | main | Angie uses a locking mechanism to implement [accept_mutex](#accept-mutex) and serialize access to shared memory. On most systems, locks are managed using atomic operations, making this directive unnecessary. On certain systems, however, an alternative lock file mechanism is used. This directive sets a prefix for lock file names. ### master_process | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `master_process` `on` | `off`; | |------------------------------------------------------------------------------------------|----------------------------------| | Default | `master_process on;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | main | Determines whether worker processes are started. This directive is intended for Angie developers. ### multi_accept | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `multi_accept` `on` | `off`; | |------------------------------------------------------------------------------------------|--------------------------------| | Default | `multi_accept off;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | events | | `on` | A worker process will accept all new connections simultaneously. | |--------|--------------------------------------------------------------------| | `off` | A worker process will accept one new connection at a time. | #### NOTE This directive is ignored if the [kqueue](https://en.angie.software//angie/docs/configuration/processing.md#kqueue) connection processing method is used, as it provides the number of new connections ready to be accepted. ### pcre_jit | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `pcre_jit` `on` | `off`; | |------------------------------------------------------------------------------------------|----------------------------| | Default | `pcre_jit off;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | main | Enables or disables "just-in-time compilation" (PCRE JIT) for regular expressions known at the time of configuration parsing. PCRE JIT can significantly accelerate regular expression processing. #### NOTE JIT is available in PCRE libraries from version 8.20, provided they are built with the `--enable-jit` configuration option. When Angie is built with the PCRE library (`--with-pcre=`), JIT support is enabled using the `--with-pcre-jit` option. ### pid | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `pid` file | `off`; | |------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| | Default | `pid logs/angie.pid;`
(the path depends on the `--pid-path` [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#paths)) | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | main | Specifies the file that will store the ID of the Angie main process. The file is created atomically, which ensures its contents are always correct. The `off` setting disables the creation of this file. #### NOTE If the file setting is modified during reconfiguration but points to a symlink of the previous PID file, the file will not be recreated. ### ssl_engine | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_engine` device; | |------------------------------------------------------------------------------------------|------------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | main | Specifies the name of the hardware SSL accelerator. ### ssl_object_cache_inheritable | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_object_cache_inheritable` `on` | `off`; | |------------------------------------------------------------------------------------------|------------------------------------------------| | Default | `ssl_object_cache_inheritable on;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | main | If enabled, SSL objects (SSL certificates, secret keys, trusted CA certificates, CRL lists) are inherited across configuration reloads. SSL objects loaded from files are inherited if their modification time and file index have not changed since the previous configuration load. Secret keys specified as `engine:name:id` are never inherited, while secret keys specified as `data:value` are always inherited. SSL objects loaded from variables cannot be inherited. Example: ```nginx ssl_object_cache_inheritable on; http { server { ssl_certificate example.com.crt; ssl_certificate_key example.com.key; } } ``` ### thread_pool | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `thread_pool` name `threads=`number [`max_queue=`number]; | |------------------------------------------------------------------------------------------|-------------------------------------------------------------| | Default | `thread_pool default threads=32 max_queue=65536;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | main | Defines the name and parameters of a thread pool used for multi-threaded reading and sending of files [without blocking](https://en.angie.software//angie/docs/configuration/modules/http/index.md#aio) worker processes. The `threads` parameter defines the number of threads in the pool. If all threads in the pool are busy executing tasks, new tasks wait in a queue. The `max_queue` parameter limits the number of tasks allowed to be waiting in the queue. By default, up to 65536 tasks can be in the queue. When the queue overflows, the task is completed with an error. ### timer_resolution | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `timer_resolution` interval; | |------------------------------------------------------------------------------------------|--------------------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | main | Reduces timer resolution in worker processes, thus reducing the number of `gettimeofday()` system calls. By default, `gettimeofday()` is called each time a kernel event is received. With reduced resolution, `gettimeofday()` is only called once per specified interval. Example: ```nginx timer_resolution 100ms; ``` Internal implementation of the interval depends on the method used: - the `EVFILT_TIMER` filter if [kqueue](https://en.angie.software//angie/docs/configuration/processing.md#kqueue) is used; - `timer_create()` if [eventport](https://en.angie.software//angie/docs/configuration/processing.md#eventport) is used; - `setitimer()` otherwise. ### use | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `use` method; | |------------------------------------------------------------------------------------------|-----------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | events | Specifies the method to use for [connection processing](https://en.angie.software//angie/docs/configuration/processing.md#methods-use). There is normally no need to specify it explicitly, because Angie will by default use the most efficient method. ### user | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `user` user [group]; | |------------------------------------------------------------------------------------------|------------------------------------------------------------| | Default | `user ;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | main | Defines user and group credentials used by worker processes (see also [build parameters](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)). If group is omitted, a group whose name equals that of user is used. ### worker_aio_requests | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `worker_aio_requests` number; | |------------------------------------------------------------------------------------------|---------------------------------| | Default | `worker_aio_requests 32;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | events | When using [aio](https://en.angie.software//angie/docs/configuration/modules/http/index.md#aio) with the [epoll](https://en.angie.software//angie/docs/configuration/processing.md#epoll) connection processing method, sets the maximum number of outstanding asynchronous I/O operations for a single worker process. ### worker_connections | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `worker_connections` number; | |------------------------------------------------------------------------------------------|--------------------------------| | Default | `worker_connections 512;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | events | Sets the maximum number of simultaneous connections that can be opened by a worker process. It should be kept in mind that this number includes all connections (e.g. connections with proxied servers, among others), not only connections with clients. Another consideration is that the actual number of simultaneous connections cannot exceed the current limit on the maximum number of open files, which can be changed by [worker_rlimit_nofile](#worker-rlimit-nofile). ### worker_cpu_affinity | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `worker_cpu_affinity` cpumask ...;

`worker_cpu_affinity` auto [cpumask]; | |------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | main | Binds worker processes to the sets of CPUs. Each CPU set is represented by a bitmask of allowed CPUs. There should be a separate set defined for each of the worker processes. By default, worker processes are not bound to any specific CPUs. For example: ```nginx worker_processes 4; worker_cpu_affinity 0001 0010 0100 1000; ``` This configuration binds each worker process to a separate CPU. Alternatively: ```nginx worker_processes 2; worker_cpu_affinity 0101 1010; ``` This binds the first worker process to CPU0 and CPU2, and the second worker process to CPU1 and CPU3. This setup is suitable for hyper-threading. The special value `auto` allows binding worker processes automatically to available CPUs: ```nginx worker_processes auto; worker_cpu_affinity auto; ``` The optional mask parameter can be used to limit the CPUs available for automatic binding: ```nginx worker_cpu_affinity auto 01010101; ``` #### NOTE The directive is only available on FreeBSD and Linux. ### worker_priority | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `worker_priority` number; | |------------------------------------------------------------------------------------------|-----------------------------| | Default | `worker_priority 0;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | main | Defines the scheduling priority for worker processes like it is done by the **nice** command: a negative number means higher priority. Allowed range normally varies from -20 to 20. Example: ```nginx worker_priority -10; ``` ### worker_processes | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `worker_processes` number | `auto`; | |------------------------------------------------------------------------------------------|---------------------------------------| | Default | `worker_processes 1;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | main | Defines the number of worker processes. The optimal value depends on many factors including (but not limited to) the number of CPU cores, the number of hard disk drives that store data, and load pattern. When one is in doubt, setting it to the number of available CPU cores would be a good start (the value "`auto`" will try to autodetect it). ### worker_rlimit_core | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `worker_rlimit_core` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units); | |------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | main | Changes the limit on the largest size of a core file (`RLIMIT_CORE`) for worker processes. Used to increase the limit without restarting the main process. ### worker_rlimit_nofile | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `worker_rlimit_nofile` number; | |------------------------------------------------------------------------------------------|----------------------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | main | Changes the limit on the maximum number of open files (`RLIMIT_NOFILE`) for worker processes. Used to increase the limit without restarting the main process. ### worker_shutdown_timeout | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `worker_shutdown_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units); | |------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | main | Configures a timeout for a graceful shutdown of worker processes. When the specified time expires, Angie will try to close all the connections currently open to facilitate shutdown. Graceful shutdown is initiated by sending a [QUIT signal](https://en.angie.software//angie/docs/configuration/runtime.md#control-signals) to the main process, which instructs worker processes to stop accepting new connections and allows existing connections to complete. Worker processes continue to handle active requests until they finish, then shut down gracefully. If connections remain open longer than `worker_shutdown_timeout`, Angie will forcibly close these connections to complete the shutdown. Also, client keep-alive connections are closed only if they have been idle for at least the time specified by [lingering_timeout](https://en.angie.software//angie/docs/configuration/modules/http/index.md#lingering-timeout). ### working_directory | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `working_directory` directory; | |------------------------------------------------------------------------------------------|----------------------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | main | Defines the current working directory for a worker process. It is primarily used when writing a core file, in which case a worker process should have write permission for the specified directory. # https://en.angie.software/angie/docs/configuration/modules/http.md # HTTP Module The core HTTP module implements the basic functionality of an HTTP server: this includes defining server blocks, configuring locations for request routing, serving static files and controlling access, configuring redirects, supporting keep-alive connections, and managing request and response headers. The other modules in this section extend this functionality, allowing you to flexibly configure and optimize the HTTP server for various scenarios and requirements. When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the HTTP server and its modules are built by default; they can be disabled altogether with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure) `--without-http`. In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the HTTP server is included in the build. ## Directives ### absolute_redirect | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `absolute_redirect` `on` | `off`; | |------------------------------------------------------------------------------------------|-------------------------------------| | Default | `absolute_redirect on;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | If disabled, redirects issued by Angie will be relative. See also [server_name_in_redirect](#server-name-in-redirect) and [port_in_redirect](#port-in-redirect) directives. ### aio | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `aio` `on` | `off` | `threads` [=pool]; | |------------------------------------------------------------------------------------------|-------------------------------------------| | Default | `aio off;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Enables or disables the use of asynchronous file I/O (AIO) on FreeBSD and Linux: ```nginx location /video/ { aio on; output_buffers 1 64k; } ``` On FreeBSD, AIO can be used starting from FreeBSD 4.3. Prior to FreeBSD 11.0, AIO can either be linked statically into a kernel: ```nginx options VFS_AIO ``` or loaded dynamically as a kernel loadable module: ```nginx kldload aio ``` On Linux, AIO can be used starting from kernel version 2.6.22. Also, it is necessary to enable [directio](#directio), or otherwise reading will be blocking: ```nginx location /video/ { aio on; directio 512; output_buffers 1 128k; } ``` On Linux, [directio](#directio) can only be used for reading blocks that are aligned on 512-byte boundaries (or 4K for XFS). File's unaligned end is read in blocking mode. The same holds true for byte range requests and for FLV requests not from the beginning of a file: reading of unaligned data at the beginning and end of a file will be blocking. When both AIO and [sendfile](#sendfile) are enabled on Linux, AIO is used for files that are larger than or equal to the size specified in the [directio](#directio) directive, while [sendfile](#sendfile) is used for files of smaller sizes or when [directio](#directio) is disabled: ```nginx location /video/ { sendfile on; aio on; directio 8m; } ``` Finally, files can be read and [sent](#sendfile) using multi-threading, without blocking a worker process: ```nginx location /video/ { sendfile on; aio threads; } ``` Read and send file operations are offloaded to threads of the specified [pool](https://en.angie.software//angie/docs/configuration/modules/core.md#thread-pool). If the pool name is omitted, the pool with the name "default" is used. The pool name can also be set with variables: ```nginx aio threads=pool$disk; ``` Using `aio on` requires building with the `--with-file-aio` configuration parameter. Using `aio threads` requires building with the `--with-threads` parameter. Currently, multi-threading is compatible only with the [epoll](https://en.angie.software//angie/docs/configuration/processing.md#epoll), [kqueue](https://en.angie.software//angie/docs/configuration/processing.md#kqueue), and [eventport](https://en.angie.software//angie/docs/configuration/processing.md#eventport) methods. Multi-threaded sending of files is only supported on Linux. See also the [sendfile](#sendfile) directive. ### aio_write | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `aio_write` `on` | `off`; | |------------------------------------------------------------------------------------------|-----------------------------| | Default | `aio_write off;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | If [aio](#aio) is enabled, specifies whether it is used for writing files. Currently, this only works when using `aio threads` and is limited to writing temporary files with data received from proxied servers. ### alias | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `alias` path; | |------------------------------------------------------------------------------------------|-----------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | location | Defines a replacement for the specified location. For example, with the following configuration: ```nginx location /i/ { alias /data/w3/images/; } ``` on request of `/i/top.gif`, the file /data/w3/images/top.gif will be sent. The path value can contain [variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables), except [$document_root](#v-document-root) and [$realpath_root](#v-realpath-root). If `alias` is used inside a location defined with a regular expression then such regular expression should contain captures and `alias` should refer to these captures, for example: ```nginx location ~ ^/users/(.+\.(?:gif|jpe?g|png))$ { alias /data/w3/images/$1; } ``` When location matches the last part of the directive's value: ```nginx location /images/ { alias /data/w3/images/; } ``` it is better to use the [root](#root) directive instead: ```nginx location /images/ { root /data/w3; } ``` #### WARNING With `alias`, the matched location prefix is stripped from the URI by its length, and the prefix itself is not re-validated. Keep the trailing slash of the location name and of the `alias` value consistent. If the `alias` value omits a trailing slash that the location has, the remainder is concatenated (e.g. `/data/w3/imagestop.gif`) and the wrong file is served; the reverse merely doubles a slash, which is usually harmless. For a location that matches the last part of the path, prefer the [root](#root) directive, which appends the whole URI and is not affected. ### auth_delay | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `auth_delay` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units); | |------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------| | Default | `auth_delay 0s;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Delays processing of unauthorized requests with 401 response code to prevent timing attacks when access is limited by [password](https://en.angie.software//angie/docs/configuration/modules/http/http_auth_basic.md#http-auth-basic) or by the [result of subrequest](https://en.angie.software//angie/docs/configuration/modules/http/http_auth_request.md#http-auth-request). ### auto_redirect | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `auto_redirect` [`on` | `off` | `default`]; | |------------------------------------------------------------------------------------------|-----------------------------------------------| | Default | `auto_redirect default;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Controls the [redirection](#location-redirect) behavior when a prefix location ends with a slash: ```nginx location /prefix/ { auto_redirect on; } ``` Here, a request for `/prefix` causes a redirect to `/prefix/`. The value `on` explicitly enables redirection, while `off` disables it. When set to `default`, redirection is enabled only if the location processes requests with [api](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#a-api), [proxy_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass), [fastcgi_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-pass), [uwsgi_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-pass), [scgi_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-pass), [memcached_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_memcached.md#memcached-pass), or [grpc_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-pass). ### chunked_transfer_encoding | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `chunked_transfer_encoding` `on` | `off`; | |------------------------------------------------------------------------------------------|---------------------------------------------| | Default | `chunked_transfer_encoding on;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Allows disabling chunked transfer encoding in HTTP/1.1. It may come in handy when using a software failing to support chunked encoding despite the standard's requirement. ### client #### Versionadded Added in version 1.10.0. #### Versionchanged Changed in version 1.10.1. | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `client` { ... } | |------------------------------------------------------------------------------------------|--------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http | Creates a special `client` context for processing internal HTTP requests that Angie performs on its own without external client involvement. The `client` context isolates service traffic from various Angie modules from user traffic, allowing additional control over it. Within this context, only named locations (with the `@` prefix) can be defined; they are not accessible for external HTTP requests and can only be called programmatically through internal server mechanisms. The `client` context is used for: - sending requests to the certificate authority in the [ACME](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme) module via the predefined `location @acme`, which can be additionally configured using directives from the [Proxy](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy) module; - requests to the Docker API in the [Docker](https://en.angie.software//angie/docs/configuration/modules/http/http_docker.md#http-docker) module via the predefined `location @docker_events` and `@docker_containers`, which can be additionally configured using directives from the [Proxy](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy) module; - health probes of proxied servers via [upstream_probe (PRO)](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe); - [sticky learn](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-sticky) mode with `remote_action` in the Stream [Upstream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#stream-upstream) module. Support for multiple `client` blocks allows grouping common settings for multiple `location` blocks within each block, which helps avoid configuration duplication. Directives specified in each `client` block are inherited only by `location` blocks explicitly declared within it. In particular, this is why they do not affect the configuration of other modules that implicitly use the `client` block for outgoing requests (for example, [ACME](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme) or [Docker](https://en.angie.software//angie/docs/configuration/modules/http/http_docker.md#http-docker)). Example of using multiple `client` blocks with settings inheritance: ```nginx client { proxy_set_header Host docker.example.com; proxy_set_header Authorization "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="; location @docker_events { } location @docker_containers { } } client { proxy_method GET; proxy_set_header Host backend.example.com; proxy_set_header X-Real-IP $remote_addr; location @health_check { proxy_pass http://upstream-server/health; } } ``` #### NOTE The same directives are allowed here as in regular `location` blocks, but only content handlers (such as [js_content](https://en.angie.software//angie/docs/configuration/modules/external-modules/http_js.md#js-content) or [autoindex](https://en.angie.software//angie/docs/configuration/modules/http/http_autoindex.md#id1)) and variable handlers (such as [map](https://en.angie.software//angie/docs/configuration/modules/http/http_map.md#id1)), as well as directives that generate requests themselves, like `upstream_probe`, actually work. Directives that operate at other [request processing stages](https://en.angie.software//angie/docs/configuration/processing.md#http-sessions) (such as [limit_req](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#limit-req), [auth_request](https://en.angie.software//angie/docs/configuration/modules/http/http_auth_request.md#id1), [try_files](#try-files), image filters, XSLT, etc.) do not work here. ### client_body_buffer_size | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `client_body_buffer_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units); | |------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------| | Default | `client_body_buffer_size 8k|16k;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Sets the buffer size for reading the client request body. If the request body is larger than the buffer, the whole body or only its part is written to a [temporary file](#client-body-temp-path). By default, the buffer size is equal to two memory pages. On x86, other 32-bit platforms, and x86-64, this is 8K. On other 64-bit platforms, it is usually 16K. ### client_body_in_file_only | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `client_body_in_file_only` `on` | `clean` | `off`; | |------------------------------------------------------------------------------------------|------------------------------------------------------| | Default | `client_body_in_file_only off;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Determines whether to save the entire client request body to a file. This directive can be used during debugging, or when using the [$request_body_file](#v-request-body-file) variable, or the [$r->request_body_file](https://en.angie.software//angie/docs/configuration/modules/http/http_perl.md#p-r-request-body-file) method of the [Perl](https://en.angie.software//angie/docs/configuration/modules/http/http_perl.md#http-perl) module. | `on` | temporary files are not removed after request processing | |---------|------------------------------------------------------------------------| | `clean` | allows the temporary files left after request processing to be removed | ### client_body_in_single_buffer | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `client_body_in_single_buffer` `on` | `off`; | |------------------------------------------------------------------------------------------|------------------------------------------------| | Default | `client_body_in_single_buffer off;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Determines whether to save the entire client request body in a single buffer. The directive is recommended when using the [$request_body](#v-request-body) variable to reduce the number of copy operations involved. ### client_body_temp_path | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `client_body_temp_path` path [level1 [level2 [level3]]]; | |------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Default | `client_body_temp_path client_body_temp;`
(the path depends on the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#paths) `--http-client-body-temp-path`) | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Defines a directory for storing temporary files with client request bodies. Up to three-level subdirectory hierarchy can be used under the specified directory. For example, in the following configuration ```nginx client_body_temp_path /spool/angie/client_temp 1 2; ``` a path to a temporary file might look like this: ```nginx /spool/angie/client_temp/7/45/00000123457 ``` ### client_body_timeout | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `client_body_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units); | |------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------| | Default | `client_body_timeout 60s;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Defines a timeout for reading client request body. The timeout is set only for a period between two successive read operations, not for the transmission of the whole request body. If a client does not transmit anything within this time, the request is terminated with the 408 (Request Time-out) error. ### client_header_buffer_size | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `client_header_buffer_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units); | |------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| | Default | `client_header_buffer_size 1k;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server | Sets buffer size for reading client request header. For most requests, a buffer of 1K bytes is enough. However, if a request includes long cookies, or comes from a WAP client, it may not fit into 1K. If a request line or a request header field does not fit into this buffer then larger buffers, configured by the [large_client_header_buffers](#large-client-header-buffers) directive, are allocated. If the directive is specified on the [server](#server) level, the value from the default server can be used. See the [Virtual server selection](https://en.angie.software//angie/docs/configuration/processing.md#request-processing) section for details. ### client_header_timeout | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `client_header_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units); | |------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------| | Default | `client_header_timeout 60s;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server | Defines a timeout for reading client request header. If a client does not transmit the entire header within this time, the request is terminated with the 408 (Request Time-out) error. ### client_max_body_size | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `client_max_body_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units); | |------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------| | Default | `client_max_body_size 1m;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Sets the maximum allowed size of the client request body. If the size in a request exceeds the configured value, the 413 (Request Entity Too Large) error is returned to the client. Please be aware that browsers cannot correctly display this error. | `0` | disables checking of client request body size | |-------|-------------------------------------------------| ### connection_pool_size | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `connection_pool_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units); | |------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------| | Default | `connection_pool_size 256` | `512;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Allows accurate tuning of per-connection memory allocations. This directive has minimal impact on performance and should not generally be used. By default: | `256` (bytes) | on 32-bit platforms | |-----------------|-----------------------| | `512` (bytes) | on 64-bit platforms | ### default_type | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `default_type` mime-type; | |------------------------------------------------------------------------------------------|-----------------------------| | Default | `default_type text/plain;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Defines the default MIME type of a response. Mapping of file name extensions to MIME types can be set with the [types](#types) directive. ### directio | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `directio` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units) | `off`; | |------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------| | Default | `directio off;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Enables the use of the `O_DIRECT` flag (FreeBSD, Linux), the `F_NOCACHE` flag (macOS), or the `directio()` function (Solaris), when reading files that are larger than or equal to the specified size. The directive automatically disables the use of [sendfile](#sendfile) for a given request. It is recommended for serving large files: ```nginx directio 4m; ``` or when using [aio](#aio) on Linux. ### directio_alignment | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `directio_alignment` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units); | |------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------| | Default | `directio_alignment 512;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Sets the alignment for [directio](#directio). In most cases, a 512-byte alignment is enough. However, when using XFS under Linux, it needs to be increased to 4K. ### disable_symlinks | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `disable_symlinks` `off`;

`disable_symlinks` `on` | `if_not_owner` [`from=`part]; | |------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------| | Default | `disable_symlinks off;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Determines how symbolic links should be treated when opening files: | `off` | Symbolic links in the path are allowed and not checked. This is the default behavior. | |----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `on` | If any component of the path is a symbolic link, access to the file is denied. | | `if_not_owner` | Access to the file is denied if any component of the path is a symbolic link, and the link and the object it points to have different owners. | | `from=`part | When checking symbolic links (parameters `on` and `if_not_owner`), all path components are usually checked. It is possible to skip checking symbolic links in the initial part of the path by additionally specifying the `from=part` parameter. In this case, symbolic links are checked only starting from the path component that follows the specified initial part. If the value is not an initial part of the checked path, the path is checked entirely, as if this parameter were not specified at all. If the value completely matches the file name, symbolic links are not checked. The parameter value can contain variables. | Example: ```nginx disable_symlinks on from=$document_root; ``` This directive is only available on systems that have the `openat()` and `fstatat()` interfaces. Such systems include modern versions of FreeBSD, Linux, and Solaris. #### WARNING The `on` and `if_not_owner` parameters add processing overhead. On systems that do not support opening directories for search only, using these parameters requires worker processes to have read permissions for all directories being checked. #### NOTE The [AutoIndex](https://en.angie.software//angie/docs/configuration/modules/http/http_autoindex.md#http-autoindex), [Random Index](https://en.angie.software//angie/docs/configuration/modules/http/http_random_index.md#http-random-index), and [DAV](https://en.angie.software//angie/docs/configuration/modules/http/http_dav.md#http-dav) modules currently ignore this directive. ### early_hints | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `early_hints` string ...; | |------------------------------------------------------------------------------------------|-----------------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Defines conditions under which the "103 Early Hints" response will be passed to a client. The response can be returned by proxied and gRPC backends. If at least one value of the string parameters is not empty and is not equal to `0` then the response will be passed: ```nginx map $http_sec_fetch_mode $early_hints { navigate $http2$http3; } server { ... location / { early_hints $early_hints; proxy_pass http://example.com; } } ``` Parameter values can contain variables. ### error_log_user_tag #### Versionadded Added in version 1.12.0. | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `error_log_user_tag` value; | |------------------------------------------------------------------------------------------|--------------------------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, limit_except | Adds a request-specific tag to [error_log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log) records. The value can [contain variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables). The directive can be specified multiple times to add multiple tags. Tags can be matched with `filter=tag:` in [error_log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log). ### error_page | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `error_page` code ... [=[response]] uri; | |------------------------------------------------------------------------------------------|--------------------------------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if in location | Defines the URI that will be shown for the specified errors. The uri value can contain variables. Example: ```nginx error_page 404 /404.html; error_page 500 502 503 504 /50x.html; ``` This causes an internal redirect to the specified uri with the client request method changed to "GET" (for all methods other than "GET" and "HEAD"). Furthermore, it is possible to change the response code to another using the syntax like `=response`, for example: ```nginx error_page 404 =200 /empty.gif; ``` If an error response is processed by a proxied server or a FastCGI/uwsgi/SCGI/gRPC server, and the server may return different response codes (e.g., 200, 302, 401, or 404), it is possible to pass the code it returns: ```nginx error_page 404 = /404.php; ``` If there is no need to change the URI and method during internal redirect, it is possible to pass error processing into a named `location`: ```nginx location / { error_page 404 = @fallback; } location @fallback { proxy_pass http://backend; } ``` #### NOTE If an error occurs during the processing of uri, the response with the code of the last occurred error is returned to the client. It is also possible to use URL redirects for error processing: ```nginx error_page 403 http://example.com/forbidden.html; error_page 404 =301 http://example.com/notfound.html; ``` In this case, by default, the response code 302 is returned to the client. It can only be changed to one of the redirect response codes (301, 302, 303, 307, and 308). ### etag | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `etag` `on` | `off`; | |------------------------------------------------------------------------------------------|------------------------| | Default | `etag on;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Enables or disables automatic generation of the `ETag` response header field for static resources. ### http | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `http` { ... } | |------------------------------------------------------------------------------------------|------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | main | Provides the configuration file context in which the HTTP server directives are specified. ### if_modified_since | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `if_modified_since` `off` | `exact` | `before`; | |------------------------------------------------------------------------------------------|---------------------------------------------------| | Default | `if_modified_since exact;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Specifies how to compare modification time of a response with the time in the `If-Modified-Since` request header field: | `off` | the response is always considered modified | |----------|---------------------------------------------------------------------------------------------------------------------| | `exact` | exact match | | `before` | modification time of the response is less than or equal to the time in the `If-Modified-Since` request header field | ### ignore_invalid_headers | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `ignore_invalid_headers` `on` | `off`; | |------------------------------------------------------------------------------------------|------------------------------------------| | Default | `ignore_invalid_headers on;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server | Controls whether Angie ignores header fields with invalid names. Valid names are composed of English letters, digits, hyphens, and possibly underscores (as controlled by the [underscores_in_headers](#underscores-in-headers) directive). If the directive is specified on the [server](#server) level, the value from the default server can be used. ### internal | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `internal;` | |------------------------------------------------------------------------------------------|---------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | location | Specifies that a given `location` can only be used for internal requests. For external requests, the client error 404 (Not Found) is returned. Internal requests are the following: * requests redirected by the [error_page](#error-page), [index](https://en.angie.software//angie/docs/configuration/modules/http/http_index.md#id1), [random_index](https://en.angie.software//angie/docs/configuration/modules/http/http_random_index.md#id1), and [try_files](#try-files) directives; * requests redirected by the `X-Accel-Redirect` response header field from an upstream server; * subrequests formed by the `include virtual` command of the [SSI](https://en.angie.software//angie/docs/configuration/modules/http/http_ssi.md#http-ssi) module, by the [Addition](https://en.angie.software//angie/docs/configuration/modules/http/http_addition.md#http-addition) module directives, and by [auth_request](https://en.angie.software//angie/docs/configuration/modules/http/http_auth_request.md#id1) and [mirror](https://en.angie.software//angie/docs/configuration/modules/http/http_mirror.md#id1) directives; * requests changed by the [rewrite](https://en.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#id5) directive; * requests redirected by the [goto](https://en.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#goto) directive. Example: ```nginx error_page 404 /404.html; location = /404.html { internal; } ``` Because the 404 error is returned in the context of a `location` with the `internal` directive, external requests can be redirected to a different location. This allows using the same prefix for both external and internal requests, but with different processing, for example: ```nginx location /path { internal; error_page 404 =@external; proxy_pass https://internal; } location @external { proxy_pass https://external; } ``` Here, an external request `GET /path` will be proxied to `https://external/path`, while the same internal request will be proxied to `https://internal/path`. #### NOTE To prevent looping that can occur with incorrect configurations, the number of internal redirects is limited to ten. When this limit is reached, the 500 (Internal Server Error) error is returned. In such cases, the `rewrite or internal redirection cycle` message can be seen in the error log. ### keepalive_disable | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `keepalive_disable` `none` | browser ...; | |------------------------------------------------------------------------------------------|---------------------------------------------| | Default | `keepalive_disable msie6;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Disables keep-alive connections with misbehaving browsers. The browser parameters specify which browsers will be affected. | `none` | enables keep-alive connections with all browsers | |----------|----------------------------------------------------------------------------------------------------------------| | `msie6` | disables keep-alive connections with old versions of MSIE, once a POST request is received | | `safari` | disables keep-alive connections with Safari and Safari-like browsers on macOS and macOS-like operating systems | ### keepalive_requests | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `keepalive_requests` number; | |------------------------------------------------------------------------------------------|--------------------------------| | Default | `keepalive_requests 1000;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Sets the maximum number of requests that can be served through one keep-alive connection. After the maximum number of requests are made, the connection is closed. Periodic closing of connections is necessary to free per-connection memory allocations. Therefore, using too high maximum number of requests could result in excessive memory usage and is not recommended. ### keepalive_time | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `keepalive_time` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units); | |------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------| | Default | `keepalive_time 1h;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Limits the maximum time during which requests can be processed through one keep-alive connection. After this time is reached, the connection is closed following the subsequent request processing. ### keepalive_timeout | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `keepalive_timeout` timeout [header_timeout]; | |------------------------------------------------------------------------------------------|-------------------------------------------------| | Default | `keepalive_timeout 75s;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | | timeout | sets a timeout during which a keep-alive client connection will stay open on the server side | |-----------|------------------------------------------------------------------------------------------------| | `0` | disables keep-alive client connections | The second, *optional*, parameter sets a value in the `Keep‑Alive: timeout=time` header field in the response. The two parameters may differ. The `Keep-Alive: timeout=time` header field is recognized by Mozilla and Konqueror. MSIE closes keep-alive connections by itself in about 60 seconds. #### NOTE This directive applies to client connections. The timeout for idle connections to proxied upstream servers is set separately by [keepalive_timeout](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive-timeout) in the upstream block. ### large_client_header_buffers | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `large_client_header_buffers` number size; | |------------------------------------------------------------------------------------------|----------------------------------------------| | Default | `large_client_header_buffers 4 8k;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server | Sets the maximum number and size of buffers used for reading large client request header. A request line cannot exceed the size of one buffer, or the 414 (Request-URI Too Large) error is returned to the client. A request header field cannot exceed the size of one buffer as well, or the 400 (Bad Request) error is returned to the client. Buffers are allocated only on demand. By default, the buffer size is equal to 8K bytes. If after the end of request processing a connection is transitioned into the keep-alive state, these buffers are released. If the directive is specified on the [server](#server) level, the value from the default server can be used. ### limit_except | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `limit_except` method1 [method2...] { ... }; | |------------------------------------------------------------------------------------------|------------------------------------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | location | Limits allowed HTTP methods inside a location. The method parameter can be one of the following: `GET`, `HEAD`, `POST`, `PUT`, `DELETE`, `MKCOL`, `COPY`, `MOVE`, `OPTIONS`, `PROPFIND`, `PROPPATCH`, `LOCK`, `UNLOCK`, or `PATCH`. Allowing the `GET` method makes the `HEAD` method also allowed. Access to other methods can be limited using the [Access](https://en.angie.software//angie/docs/configuration/modules/http/http_access.md#http-access) and [Auth Basic](https://en.angie.software//angie/docs/configuration/modules/http/http_auth_basic.md#http-auth-basic) module directives: ```nginx limit_except GET { allow 192.168.1.0/32; deny all; } ``` #### NOTE The restriction in this example applies to all methods **except** `GET` and `HEAD`. ### limit_rate | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `limit_rate` rate; | |------------------------------------------------------------------------------------------|----------------------------------------| | Default | `limit_rate 0;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if in location | Limits the rate of response transmission to a client. The rate is specified in bytes per second. The zero value disables rate limiting. The limit is set per a request, and so if a client simultaneously opens two connections, the overall rate will be twice as much as the specified limit. Parameter value can contain variables. It may be useful in cases where rate should be limited depending on a certain condition: ```nginx map $slow $rate { 1 4k; 2 8k; } limit_rate $rate; ``` Rate limit can also be set in the [$limit_rate](#v-limit-rate) variable, however, this method is not recommended: ```nginx server { if ($slow) { set $limit_rate 4k; } } ``` Rate limit can also be set in the `X-Accel-Limit-Rate` header field of a proxied server response. This capability can be disabled using the [proxy_ignore_headers](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ignore-headers), [fastcgi_ignore_headers](https://en.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-ignore-headers), [uwsgi_ignore_headers](https://en.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-ignore-headers), and [scgi_ignore_headers](https://en.angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-ignore-headers) directives. ### limit_rate_after | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `limit_rate_after` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units); | |------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------| | Default | `limit_rate_after 0;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if in location | Sets the initial amount after which the further transmission of a response to a client will be rate limited. Parameter value can contain variables. Example: ```nginx location /flv/ { flv; limit_rate_after 500k; limit_rate 50k; } ``` ### lingering_close | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `lingering_close` `on` | `always` | `off`; | |------------------------------------------------------------------------------------------|----------------------------------------------| | Default | `lingering_close on;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Controls how Angie closes client connections. | `on` | Angie will [wait for](#lingering-timeout) and [process](#lingering-time) additional data from a client before fully closing a connection, but only if heuristics suggests that a client may be sending more data. | |----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `always` | Angie will always wait for and process additional client data. | | `off` | Angie will not wait for more data and will close the connection immediately. This behavior breaks the protocol and should not be used under normal circumstances. | To control closing of HTTP/2 connections, the directive must be specified at the [server](#server) level. ### lingering_time | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `lingering_time` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units); | |------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------| | Default | `lingering_time 30s;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | When [lingering_close](#lingering-close) is in effect, this directive specifies the maximum time during which Angie will process (read and ignore) additional data coming from a client. After that, the connection will be closed, even if there will be more data. ### lingering_timeout | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `lingering_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units); | |------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------| | Default | `lingering_timeout 5s;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | When [lingering_close](#lingering-close) is in effect, this directive specifies the maximum waiting time for more client data to arrive. If data are not received during this time, the connection is closed. Otherwise, the data are read and ignored, and Angie starts waiting for more data again. The "wait-read-ignore" cycle is repeated, but no longer than specified by the [lingering_time](#lingering-time) directive. During graceful shutdown, client keepalive connections are closed only when they have been idle for at least the time specified in `lingering_timeout`. #### NOTE In nginx, the analogous directive is called [keepalive_min_timeout](https://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_min_timeout). ### listen #### Versionchanged Changed in version 1.10.0. | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `listen` address[:port] [`default_server`] [`ssl`] [http2 | `quic`] [`proxy_protocol`] [`setfib=`number] [`fastopen=`number] [`backlog=`number] [`rcvbuf=`size] [`sndbuf=`size] [`accept_filter=`filter] [`deferred`] [`bind`] [`ipv6only=``on` | `off`] [`reuseport`] [`so_keepalive=`on|off|[`keepidle`]:[`keepintvl`]:[`keepcnt`]];

`listen` port [`default_server`] [`ssl`] [http2 | `quic`] [`proxy_protocol`] [`setfib=`number] [`fastopen=`number] [`backlog=`number] [`rcvbuf=`size] [`sndbuf=`size] [`accept_filter=`filter] [`deferred`] [`bind`] [`ipv6only=``on` | `off`] [`reuseport`] [`so_keepalive=`on|off|[`keepidle`]:[`keepintvl`]:[`keepcnt`]];

`listen` unix:path [`default_server`] [`ssl`] [http2 | `quic`] [`proxy_protocol`] [`backlog=`number] [`rcvbuf=`size] [`sndbuf=`size] [`accept_filter=`filter] [`deferred`] [`bind`] [`so_keepalive=`on|off|[`keepidle`]:[`keepintvl`]:[`keepcnt`]]; | |------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Default | `listen *:80` | `*:8000;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | server | Sets the address and port for the listening socket, or the path for a UNIX domain socket on which the server will accept requests. An address may also be a hostname, for example: ```nginx listen 127.0.0.1:8000; listen 127.0.0.1; listen 8000; listen *:8000; listen localhost:8000; ``` IPv6 addresses are specified in square brackets: ```nginx listen [::]:8000; listen [::1]; ``` Port ranges are specified with the first and last port separated by a hyphen: ```nginx listen 127.0.0.1:8000-8009; listen 8000-8009; ``` UNIX domain sockets are specified with the `unix:` prefix: ```nginx listen unix:/var/run/angie.sock; ``` Both address and port, or only address or only port, can be specified. When some parts are omitted, the following rules apply: - If only the address is given, port 80 is used. - If only the port is given, Angie listens on all available IPv4 (and IPv6, if enabled) interfaces. The first `server` block for that port becomes the default server for requests with an unmatched `Host` header. - If the directive is omitted entirely, Angie uses `*:80` when running with superuser privileges or `*:8000` otherwise. | `default_server` | The server with this parameter specified
will be the default server for the given address:port pair
(together they form a *listening socket*).

If there are no directives with the `default_server` parameter,
the default server for the listening socket
will be the first server in the configuration that serves this socket. | |--------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `ssl` | indicates that all connections accepted on this listening socket should work in SSL mode. This allows for a more [compact configuration](https://en.angie.software//angie/docs/configuration/ssl.md#compact-server) for the server that handles both HTTP and HTTPS requests. | | `http2` | configures the port to accept HTTP/2 connections. Normally, for this to work the `ssl` parameter should be specified as well, but Angie can also be configured to accept HTTP/2 connections without SSL.

#### Deprecated
Deprecated since version 1.2.0: Use the [http2](https://en.angie.software//angie/docs/configuration/modules/http/http_v2.md#http2) directive instead. | | `quic` | configures the port to accept QUIC connections.
To use this option,
Angie must have the [HTTP/3](https://en.angie.software//angie/docs/configuration/modules/http/http_v3.md#http-v3) module
enabled and configured.
With `quic` set,
you can also specify `reuseport`
so multiple worker processes can be used. | | `proxy_protocol` | indicates that all connections accepted on this listening socket should use the PROXY protocol. | The `listen` directive can also specify several additional parameters specific to socket-related system calls. These parameters can be specified in any `listen` directive, but only once for a given listening socket: | `setfib=`number | sets the routing table, FIB (the `SO_SETFIB` option) for the listening socket. This currently works only on FreeBSD. | |--------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `fastopen=`number | enables "TCP Fast Open" for the listening socket and limits the maximum length for the queue of connections that have not yet completed the three-way handshake.

#### WARNING
Do not enable "TCP Fast Open" unless the server can handle receiving the same SYN packet with data more than once. | | `backlog=`number | sets the `backlog` parameter in the `listen()` call that
limits the maximum length for the queue of pending connections. By
default, backlog is set to -1 on FreeBSD, DragonFly BSD, and macOS, and
to 511 on other platforms. | | `rcvbuf=`size | sets the receive buffer size (the `SO_RCVBUF` option) for the
listening socket. | | `sndbuf=`size | sets the send buffer size (the `SO_SNDBUF` option) for the
listening socket. | | `accept_filter=`filter | sets the name of accept filter (the `SO_ACCEPTFILTER` option) for
the listening socket that filters incoming connections before passing
them to `accept()`. This works only on FreeBSD and NetBSD 5.0+.
Possible values are `dataready` and `httpready`. | | `deferred` | instructs to use a deferred `accept()` (the
`TCP_DEFER_ACCEPT` socket option) on Linux. | | `bind` | instructs to make a separate `bind()` call for a given address:port
pair. This is useful because if there are several `listen`
directives with the same port but different addresses, and one of the
`listen` directives listens on all addresses for the given
`port` (`*:port`), Angie will `bind()` only to
`*:port`. It should be noted that the `getsockname()` system
call will be made in this case to determine the address that accepted the
connection. If the `setfib`, `fastopen`, `backlog`,
`rcvbuf`, `sndbuf`, `accept_filter`, `deferred`,
`ipv6only`, `reuseport` or `so_keepalive` parameters
are used then for a given `address:port` pair a separate `bind()`
call will always be made. | | `ipv6only=on` | `off` | determines (via the `IPV6_V6ONLY` socket option)
whether an IPv6 socket listening on a wildcard address [::] will accept
only IPv6 connections or both IPv6 and IPv4 connections. This parameter
is turned on by default. It can only be set once on start. | | `reuseport` | instructs to create an individual listening socket for
each worker process (using the `SO_REUSEPORT` socket option on
Linux 3.9+ and DragonFly BSD, or `SO_REUSEPORT_LB` on FreeBSD 12+),
allowing a kernel to distribute incoming connections between worker
processes. This currently works only on Linux 3.9+, DragonFly BSD, and
FreeBSD 12+.

#### WARNING
Inappropriate use of the `reuseport` parameter
may have security implications. | | `multipath` | enables accepting connections via [Multipath TCP](https://en.wikipedia.org/wiki/Multipath_TCP) (MPTCP),
supported in the Linux kernel since version 5.6.
This parameter is **incompatible** with `quic`. | | `so_keepalive=on` | `off` | [`keepidle`]:[`keepintvl`]:[`keepcnt`] | configures the "TCP keepalive" behavior for the listening socket.

| `''` | if this parameter is omitted then the operating system's settings will be in effect for the socket |
|--------|------------------------------------------------------------------------------------------------------|
| `on` | the `SO_KEEPALIVE` option is turned on for the socket |
| `off` | the `SO_KEEPALIVE` option is turned off for the socket | | Some operating systems support setting of TCP keepalive parameters on a per-socket basis using the `TCP_KEEPIDLE`, `TCP_KEEPINTVL`, and `TCP_KEEPCNT` socket options. On such systems (currently, Linux, NetBSD, Dragonfly, FreeBSD, and macOS), they can be configured using the `keepidle`, `keepintvl`, and `keepcnt` parameters. One or two parameters may be omitted, in which case the system default setting for the corresponding socket option will be in effect. For example, ```nginx so_keepalive=30m::10 ``` will set the idle timeout (`TCP_KEEPIDLE`) to 30 minutes, leave the probe interval (`TCP_KEEPINTVL`) at its system default, and set the probes count (`TCP_KEEPCNT`) to 10 probes. Example: ```nginx listen 127.0.0.1 default_server accept_filter=dataready backlog=1024; ``` ### location | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `location` ([ = | ~ | ~\* | ^~ ] uri | `@name`)+ { ... } | |------------------------------------------------------------------------------------------|------------------------------------------------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | server, location | Sets the configuration depending on whether the request URI matches any of the matching expressions. The matching is performed against the normalized request URI (the value of [$uri](#v-uri)), after decoding the text encoded in the "%XX" form, resolving references to relative path components "." and "..", and possible [compression](#merge-slashes) of two or more adjacent slashes into a single slash. A `location` can either be defined by a prefix string, or by a regular expression. Regular expressions are specified with the preceding modifier: | `~*` | Case-insensitive matching | |--------|-----------------------------| | `~` | Case-sensitive matching | To find a location that matches a request, Angie first checks the locations defined with prefix strings (prefix locations). Among them, the location with the longest matching prefix is selected and remembered. #### NOTE For case-insensitive operating systems such as macOS, prefix string matching is case insensitive. However, matching is limited to single-byte locales. Then regular expressions are checked in the order of their appearance in the configuration file. The search stops after the first match, and the corresponding configuration is used. If no match with a regular expression is found, then the configuration of the prefix location remembered earlier is used. With some exceptions mentioned below, `location` blocks can be nested. Regular expressions can create capture groups that can later be used with other directives. If the longest matching prefix location has the `^~` modifier, then regular expressions are not checked. Also, using the `=` modifier, it is possible to define an exact match of URI and location. If an exact match is found, the search terminates. For example, if a `/` request happens frequently, defining `location =/` will speed up the processing of these requests, as the search terminates after the first comparison. Such a location cannot contain nested locations, as it defines an exact match. Once a matching `location` is selected, the request is mapped to a file through the [root](#root) or [alias](#alias) directive, and [try_files](#try-files) can probe for files within it; see [Choosing locations](https://en.angie.software//angie/docs/configuration/processing.md#pick-location) for an overview. Example: ```nginx location =/ { #configuration A } location / { #configuration B } location /documents/ { #configuration C } location ^~/images/ { #configuration D } location ~*\.(gif|jpg|jpeg)$ { #configuration E } ``` - A `/` request will match configuration A, - an `/index.html` request will match configuration B, - a `/documents/document.html` request will match configuration C, - an `/images/1.gif` request will match configuration D, - and a `/documents/1.jpg` request will match configuration E. #### NOTE If a prefix `location` ends with a slash character and [auto_redirect](#auto-redirect) is enabled, the following occurs: When a request arrives with a URI that has no trailing slash but otherwise matches the prefix exactly, a permanent redirect with code 301 is returned, pointing to the requested URI with a slash appended. With an exact URI-matching location, redirection isn't applied: ```nginx location /user/ { proxy_pass http://user.example.com; } location =/user { proxy_pass http://login.example.com; } ``` The `@` prefix defines a *named* `location`. Such locations aren't used for regular request processing, but instead are only intended for request redirection. They cannot be nested and cannot contain nested locations. #### Combined locations Several `location` contexts that define identical configuration blocks can be compacted by listing all their matching expressions in a single `location` with a single configuration block. That's called a *combined* `location`. Suppose that configurations A, D, and E from the previous example define identical configurations; you can combine them into one `location`: ```nginx location =/ ^~/images/ ~*\.(gif|jpg|jpeg)$ { # general configuration } ``` A named `location` can also be a part of the combination: ```nginx location =/ @named_combined { #... } ``` #### WARNING A combined `location` can't have a space between the matching expression modifier and the expression itself. Proper form: `location ~*/match(ing|es|er)$ *...*`. #### NOTE Currently, a combined `location` cannot **immediately** contain `proxy_pass` directives with URI set, nor `api` or `alias`. However, these directives can be used by locations nested inside a combined location. ### log_not_found | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `log_not_found` `on` | `off`; | |------------------------------------------------------------------------------------------|---------------------------------| | Default | `log_not_found on;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Enables or disables logging of errors about not found files into [error_log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log). ### log_subrequest | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `log_subrequest` `on` | `off`; | |------------------------------------------------------------------------------------------|----------------------------------| | Default | `log_subrequest off;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Enables or disables logging of subrequests into [access_log](https://en.angie.software//angie/docs/configuration/modules/http/http_log.md#access-log). ### max_headers | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `max_headers` number; | |------------------------------------------------------------------------------------------|-------------------------| | Default | `max_headers 1000;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server | Sets the maximum number of client request header fields allowed. If this limit is exceeded, a `400 (Bad Request)` error is returned. When this directive is set at the [server](#server) level, the value from the default server may be applied. For more information, refer to the [Virtual server selection](https://en.angie.software//angie/docs/configuration/processing.md#virtual-server-selection) section. ### max_ranges | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `max_ranges` number; | |------------------------------------------------------------------------------------------|------------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Limits the maximum allowed number of ranges in byte-range requests. Requests that exceed the limit are processed as if there were no byte ranges specified. By default, the number of ranges is not limited. | `0` | disables the byte-range support completely | |-------|----------------------------------------------| ### merge_slashes | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `merge_slashes` `on` | `off`; | |------------------------------------------------------------------------------------------|---------------------------------| | Default | `merge_slashes on;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server | Enables or disables compression of two or more adjacent slashes in a URI into a single slash. Note that compression is essential for the correct matching of prefix string and regular expression locations. Without it, the `//scripts/one.php` request would not match ```nginx location /scripts/ { } ``` and might be processed as a static file. So it gets converted to `/scripts/one.php`. Turning the compression off can become necessary if a URI contains base64-encoded names, since base64 uses the "/" character internally. However, for security considerations, it is better to avoid turning the compression off. If the directive is specified on the [server](#server) level, the value from the default server can be used. ### msie_padding | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `msie_padding` `on` | `off`; | |------------------------------------------------------------------------------------------|--------------------------------| | Default | `msie_padding on;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Enables or disables adding comments to responses for MSIE clients with status greater than 400 to increase the response size to 512 bytes. ### msie_refresh | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `msie_refresh` `on` | `off`; | |------------------------------------------------------------------------------------------|--------------------------------| | Default | `msie_refresh off;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Enables or disables issuing refreshes instead of redirects for MSIE clients. ### open_file_cache | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `open_file_cache` `off`;

`open_file_cache` `max=`N [`inactive=`time]; | |------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------| | Default | `open_file_cache off;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Configures a cache that can store: * open file descriptors, their sizes and modification times; * information on existence of directories; * file lookup errors, such as "file not found", "no read permission", and so on. Caching of errors should be enabled separately by the [open_file_cache_errors](#open-file-cache-errors) directive. | `max` | sets the maximum number of elements in the cache; on cache overflow the least recently used (LRU) elements are removed | |------------|-----------------------------------------------------------------------------------------------------------------------------------------------| | `inactive` | defines a time after which an element is removed from the cache if it has not been accessed during this time;

by default, 60 seconds | | `off` | disables the cache | Example: ```nginx open_file_cache max=1000 inactive=20s; open_file_cache_valid 30s; open_file_cache_min_uses 2; open_file_cache_errors on; ``` ### open_file_cache_errors | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `open_file_cache_errors` `on` | `off`; | |------------------------------------------------------------------------------------------|------------------------------------------| | Default | `open_file_cache_errors off;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Enables or disables caching of file lookup errors by [open_file_cache](#open-file-cache). ### open_file_cache_events | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `open_file_cache_events` `on` | `off`; | |------------------------------------------------------------------------------------------|------------------------------------------| | Default | `open_file_cache_events off;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Enables the use of kernel events to validate [open_file_cache](#open-file-cache) elements. This directive works with the [kqueue](https://en.angie.software//angie/docs/configuration/processing.md#kqueue) method only. Note that only NetBSD 2.0+ and FreeBSD 6.0+ support events for arbitrary file system types; other operating systems support events only for essential file systems such as UFS or FFS. ### open_file_cache_min_uses | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `open_file_cache_min_uses` number; | |------------------------------------------------------------------------------------------|--------------------------------------| | Default | `open_file_cache_min_uses 1;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Sets the minimum number of file accesses during the period configured by the `inactive` parameter of the [open_file_cache](#open-file-cache) directive, required for a file descriptor to remain open in the cache. ### open_file_cache_valid | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `open_file_cache_valid` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units); | |------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------| | Default | `open_file_cache_valid 60s;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Sets a time after which [open_file_cache](#open-file-cache) elements should be validated. ### output_buffers | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `output_buffers` number [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units); | |------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------| | Default | `output_buffers 2 32k;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Sets the number and size of the buffers used for reading a response from a disk. ### port_in_redirect | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `port_in_redirect` `on` | `off`; | |------------------------------------------------------------------------------------------|------------------------------------| | Default | `port_in_redirect on;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Enables or disables specifying the port in [absolute](#absolute-redirect) redirects issued by Angie. The use of the primary server name in redirects is controlled by the [server_name_in_redirect](#server-name-in-redirect) directive. ### postpone_output | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `postpone_output` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units); | |------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------| | Default | `postpone_output 1460;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | If possible, the transmission of client data will be postponed until Angie has at least the specified number of bytes to send. | `0` | disables postponing data transmission | |-------|-----------------------------------------| ### read_ahead | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `read_ahead` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units); | |------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------| | Default | `read_ahead 0;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Sets the amount of pre-reading for the kernel when working with files. On Linux, the `posix_fadvise(0, 0, 0, POSIX_FADV_SEQUENTIAL)` system call is used, and so the size parameter is ignored. On FreeBSD, the `fcntl(O_READAHEAD,` size ) system call, supported since FreeBSD 9.0-CURRENT, is used. ### recursive_error_pages | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `recursive_error_pages` `on` | `off`; | |------------------------------------------------------------------------------------------|-----------------------------------------| | Default | `recursive_error_pages off;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Enables or disables doing several redirects using the [error_page](#error-page) directive. The number of such redirects is [limited](#internal). ### request_pool_size | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `request_pool_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units); | |------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------| | Default | `request_pool_size 4k;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server | Allows accurate tuning of per-request memory allocations. This directive has minimal impact on performance and should not generally be used. ### reset_timedout_connection | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `reset_timedout_connection` `on` | `off`; | |------------------------------------------------------------------------------------------|---------------------------------------------| | Default | `reset_timedout_connection off;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Enables or disables resetting timed-out connections and connections closed with the non-standard code 444. The reset is performed as follows. Before closing a socket, the `SO_LINGER` option is set for it with a timeout value of 0. When the socket is closed, TCP RST is sent to the client, and all memory associated with this socket is released. This helps avoid keeping an already closed socket in the FIN_WAIT1 state with filled buffers for a long time. #### NOTE keep-alive connections are closed normally when they time out. ### resolver #### Versionchanged Changed in version 1.12.0. | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `resolver` [address ...] [`conf` [`=`file]] [`valid=`time] [`ipv4=``on` | `off`] [`ipv6=``on` | `off`] [`status_zone=`zone];

`resolver` `off`; | |------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------| | Default | `resolver conf;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, upstream | Configures name servers used to resolve names of upstream servers into addresses, for example: ```nginx resolver 127.0.0.53 [::1]:5353; ``` The address can be specified as a domain name or IP address, with an optional port. If port is not specified, the port 53 is used. Name servers are queried in a round-robin fashion. At least one DNS server address or the `conf` parameter must be specified, except in the `resolver off;` form. #### NOTE Prefer a local trusted resolver such as `127.0.0.53` (systemd-resolved) over a public one (e.g. `8.8.8.8`). Public resolvers expose DNS queries to third parties and increase susceptibility to cache-poisoning attacks. #### NOTE The directive value is inherited by nested blocks and can be overridden in them if necessary. Within a single block the directive may be specified only once; repeating it is a configuration error. Enables DNS resolution for upstream servers referenced through variables or configured with the [resolve](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve) parameter, and for the ACME client and OCSP stapling. Besides explicit server addresses, the directive recognizes: | `off` | explicitly disables DNS name resolution | |------------------|------------------------------------------------------------------------------------------------------------| | `conf` [`=`file] | reads DNS server addresses from the specified file, or from
`/etc/resolv.conf` if no file is specified | The file may contain `nameserver` lines in the same format used by the system resolver: ```text nameserver 127.0.1.4 nameserver 127.0.1.5 ``` Addresses read from the file are added to any addresses specified explicitly in the directive, and all of them are then queried together in a round-robin fashion. If the file is absent, cannot be read, or lists no addresses, and none are configured explicitly, Angie falls back to the default server `127.0.0.1:53`. At runtime, Angie re-reads the file when it changes, updating the set of DNS servers. By default, Angie caches each answer for the duration of the TTL value in the DNS response. The optional `valid` parameter overrides this: | `valid` | *optional* parameter allows overriding the response cache validity period | |-----------|-----------------------------------------------------------------------------| ```nginx resolver 127.0.0.53 [::1]:5353 valid=30s; ``` By default, Angie will look up both IPv4 and IPv6 addresses while resolving. | `ipv4=off` | disables looking up of IPv4 addresses | |--------------|-----------------------------------------| | `ipv6=off` | disables looking up of IPv6 addresses | | `status_zone` | *optional* parameter;
enables the collection of DNS server request and response metrics
in the specified zone, exposing them in [/status/resolvers/](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-resolvers),
the [DNS Resolvers Tab](https://en.angie.software//angie/docs/configuration/monitoring.md#samp-dns-resolvers-tab), and [Prometheus](https://en.angie.software//angie/docs/configuration/modules/http/http_prometheus.md#http-prometheus) output.
Without it, these metrics are not collected and no warning is logged | |-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ### resolver_timeout | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `resolver_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units); | |------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------| | Default | `resolver_timeout 30s;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, upstream | Sets a timeout for name resolution, for example: ```nginx resolver_timeout 5s; ``` ### root | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `root` path; | |------------------------------------------------------------------------------------------|----------------------------------------| | Default | `root html;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if in location | Sets the root directory for requests. For example, with the following configuration ```nginx location /i/ { root /data/w3; } ``` The `/data/w3/i/top.gif` file will be sent in response to the `/i/top.gif` request. The path value can contain variables, except [$document_root](#v-document-root) and [$realpath_root](#v-realpath-root). A path to the file is constructed by merely adding a URI to the value of the root directive. If a URI has to be modified, the [alias](#alias) directive should be used. A trailing slash in the path value is dropped, since the URI is appended with its own leading slash. ### satisfy | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `satisfy` `all` | `any`; | |------------------------------------------------------------------------------------------|----------------------------| | Default | `satisfy all;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Allows access if all (`all`) or at least one (`any`) of the [Access](https://en.angie.software//angie/docs/configuration/modules/http/http_access.md#http-access), [Auth Basic](https://en.angie.software//angie/docs/configuration/modules/http/http_auth_basic.md#http-auth-basic), or [Auth Request](https://en.angie.software//angie/docs/configuration/modules/http/http_auth_request.md#http-auth-request) modules allow access. ```nginx location / { satisfy any; allow 192.168.1.0/32; deny all; auth_basic "closed site"; auth_basic_user_file conf/htpasswd; } ``` ### send_lowat | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `send_lowat` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units); | |------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------| | Default | `send_lowat 0;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | If the directive is set to a non-zero value, Angie will try to minimize the number of send operations on client sockets by using either the `NOTE_LOWAT` flag of the [kqueue](https://en.angie.software//angie/docs/configuration/processing.md#kqueue) method or the `SO_SNDLOWAT` socket option. In both cases the specified size is used. ### send_timeout | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `send_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units); | |------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------| | Default | `send_timeout 60s;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Sets a timeout for transmitting a response to the client. The timeout is set only between two successive write operations, not for the transmission of the whole response. If the client does not receive anything within this time, the connection is closed. ### sendfile | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `sendfile` `on` | `off`; | |------------------------------------------------------------------------------------------|----------------------------------------| | Default | `sendfile off;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if in location | Enables or disables the use of `sendfile()`. [aio](#aio) can be used to pre-load data for `sendfile()`: ```nginx location /video/ { sendfile on; tcp_nopush on; aio on; } ``` In this configuration, `sendfile()` is called with the `SF_NODISKIO` flag which causes it not to block on disk I/O, but, instead, report back that the data are not in memory. Angie then initiates an asynchronous data load by reading one byte. On the first read, the FreeBSD kernel loads the first 128K bytes of a file into memory, although next reads will only load data in 16K chunks. This can be changed using the [read_ahead](#read-ahead) directive. ### sendfile_max_chunk | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `sendfile_max_chunk` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units); | |------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------| | Default | `sendfile_max_chunk 2m;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Limits the amount of data that can be transferred in a single `sendfile()` call. Without the limit, one fast connection may seize the worker process entirely. ### server | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `server` { ... } | |------------------------------------------------------------------------------------------|--------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http | Sets configuration for a virtual server. There is no clear separation between IP-based (based on the IP address) and name-based (based on the "Host" request header field) virtual servers. Instead, the [listen](#listen) directives describe all addresses and ports that should accept connections for the server, and the [server_name](#server-name) directive lists all server names. Example configurations are provided in the [How Angie processes a request](https://en.angie.software//angie/docs/configuration/processing.md#request-processing) document. ### server_name | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `server_name` name ...; | |------------------------------------------------------------------------------------------|---------------------------| | Default | `server_name ""`; | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | server | Sets names of a virtual server, for example: ```nginx server { server_name example.com www.example.com; } ``` The first name becomes the primary server name. Server names can include an asterisk ("\*") replacing the first or last part of a name: ```nginx server { server_name example.com *.example.com www.example.*; } ``` Such names are called wildcard names. The first two of the names mentioned above can be combined in one: ```nginx server { server_name .example.com; } ``` It is also possible to use regular expressions in server names, preceding the name with a tilde ("~"): ```nginx server { server_name ~^www\d+\.example\.com$ www.example.com; } ``` Regular expressions can contain captures that can later be used in other directives: ```nginx server { server_name ~^(www\.)?(.+)$; location / { root /sites/$2; } } server { server_name _; location / { root /sites/default; } } ``` Named captures in regular expressions create variables that can later be used in other directives: ```nginx server { server_name ~^(www\.)?(?.+)$; location / { root /sites/$domain; } } server { server_name _; location / { root /sites/default; } } ``` #### NOTE If the directive's parameter is set to [$hostname](#v-hostname), the machine name is used. An empty server name can also be specified: ```nginx server { server_name www.example.com ""; } ``` When searching for a virtual server by name, if the name matches more than one of the specified variants (for example, both a wildcard name and regular expression match), the first matching variant will be chosen, in the following order of priority: - exact name; - longest wildcard name starting with an asterisk, e.g. `*.example.com`; - longest wildcard name ending with an asterisk, e.g. `mail.*`; - first matching regular expression (in order of appearance in the configuration file), including an empty name. #### WARNING To use `server_name` with TLS, TLS connection termination is required. This directive matches against the `Host` in the HTTP request, so the handshake must be completed and the connection decrypted. ### server_name_in_redirect | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `server_name_in_redirect` `on` | `off`; | |------------------------------------------------------------------------------------------|-------------------------------------------| | Default | `server_name_in_redirect off`; | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Enables or disables the use of the primary server name, specified by the [server_name](#server-name) directive, in [absolute](#absolute-redirect) redirects issued by Angie. | `on` | the primary server name set by the [server_name](#server-name) directive is used | |--------|----------------------------------------------------------------------------------------------------------------------------| | `off` | the name from the "Host" request header field is used. If this field is not present, the IP address of the server is used. | The use of the port in redirects is controlled by the [port_in_redirect](#port-in-redirect) directive. ### server_names_hash_bucket_size | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `server_names_hash_bucket_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units); | |------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------| | Default | `server_names_hash_bucket_size 32` | `64` | `128;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http | Sets the bucket size for the server names hash tables. The default value depends on the size of the processor's cache line. The details of setting up hash tables are provided in a [separate document](https://en.angie.software//angie/docs/configuration/configfile.md#configure-hashes). ### server_names_hash_max_size | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `server_names_hash_max_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units); | |------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------| | Default | `server_names_hash_max_size 512`; | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http | Sets the maximum size of the server names hash tables. The details of setting up hash tables are provided in a [separate document](https://en.angie.software//angie/docs/configuration/configfile.md#configure-hashes). ### server_tokens | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `server_tokens` `on` | `off` | `build` | string; | |------------------------------------------------------------------------------------------|----------------------------------------------------| | Default | `server_tokens on;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Enables or disables emitting Angie version on error pages and in the `Server` response header field. The `build` parameter enables emitting the build name, set by the respective [configure](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure) parameter, along with the version. In Angie PRO, if the directive sets a string, which may also contain variables, the error pages and the `Server` response header field will use the string's variable-interpolated value instead of server name, version, and build name. An empty string disables emitting the `Server` field. ### status_zone #### Versionchanged Changed in version 1.12.0. | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `status_zone` `off` | zone | key `zone=`zone[:number]; | |------------------------------------------------------------------------------------------|----------------------------------------------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | server, location, if in location | Allocates a shared memory zone for collecting [/status/http/location_zones/](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-location-zones) and [/status/http/server_zones/](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-server-zones) metrics. Several `server` contexts can share the same zone for data collection; the special value `off` disables data collection in nested `location` blocks. The syntax with a single zone value combines all metrics for the current context into one shared memory zone: ```nginx server { listen 80; server_name *.example.com; status_zone single; # ... } ``` The alternative syntax allows setting the following parameters: | key | A string with variables, whose value determines the grouping of requests in
the zone. All requests producing identical values after substitution
are grouped together. If substitution yields an empty value,
metrics aren't updated. | |-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | zone | The name of the shared memory zone. | | number (optional) | The maximum number of separate groups for collecting metrics.
If new key values would exceed this limit, they are grouped under `zone` instead.

The default value is 1. | In the following example, all requests sharing the same `$host` value are grouped into the `host_zone`. Metrics are tracked separately for each unique `$host` until there are 10 metric groups. Once this limit is reached, any additional `$host` values are included under the `host_zone`: ```nginx server { listen 80; server_name *.example.com; status_zone $host zone=host_zone:10; location / { proxy_pass http://example.com; } } ``` The resulting metrics are thus split between individual hosts in the API output. #### NOTE These metrics are collected only when `status_zone` is set. Without it, the server or location does not appear in [/status/http/server_zones/](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-server-zones), [/status/http/location_zones/](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-location-zones), the [HTTP Zones Widget](https://en.angie.software//angie/docs/configuration/monitoring.md#http-zones-widget), or [Prometheus](https://en.angie.software//angie/docs/configuration/modules/http/http_prometheus.md#http-prometheus) output, and no warning is logged. See [Example configuration](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#example-configuration). ### subrequest_output_buffer_size | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `subrequest_output_buffer_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units); | |------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------| | Default | `subrequest_output_buffer_size 4k` | `8k;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Sets the size of the buffer used for storing the response body of a subrequest. By default, the buffer size is equal to one memory page. This is either `4K` or `8K`, depending on a platform. It can be made smaller, however. #### NOTE The directive is applicable only for subrequests with response bodies saved into memory. For example, such subrequests are created by [SSI](https://en.angie.software//angie/docs/configuration/modules/http/http_ssi.md#ssi-include-set). ### tcp_nodelay | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `tcp_nodelay` `on` | `off`; | |------------------------------------------------------------------------------------------|-------------------------------| | Default | `tcp_nodelay on;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Enables or disables the use of the `TCP_NODELAY` option. The option is enabled when a connection is transitioned into the keep-alive state. Additionally, it is enabled on SSL connections, for unbuffered proxying, and for [WebSocket proxying](https://en.angie.software//angie/docs/configuration/processing.md#websocket-proxy). ### tcp_nopush | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `tcp_nopush` `on` | `off`; | |------------------------------------------------------------------------------------------|------------------------------| | Default | `tcp_nopush off`; | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Enables or disables the use of the `TCP_NOPUSH` socket option on FreeBSD or the `TCP_CORK` socket option on Linux. The options are enabled only when [sendfile](#sendfile) is used. Enabling the option allows * sending the response header and the beginning of a file in one packet, on Linux and FreeBSD 4.\*; * sending a file in full packets. ### time_format #### Versionadded Added in version 1.12.0. | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `time_format` $variable format; | |------------------------------------------------------------------------------------------|-----------------------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http | Defines a $variable to hold the current local time, rendered with a custom format string of `strftime`-like specifiers plus `%L` for milliseconds. The directive is useful where [$time_local](#v-time-local) and [$time_iso8601](#v-time-iso8601) fall short, for example because they provide no sub-second precision: ```nginx time_format $time_ms "%Y-%m-%dT%H:%M:%S.%L%Z"; log_format tf '$time_ms $remote_addr "$request" $status'; ``` With the format above, `$time_ms` expands to a value such as `2024-01-15T14:34:56.789+03:00`. Redefining a built-in variable, such as [$time_local](#v-time-local), or repeating `time_format` for the same name fails the configuration load with an error like: "the duplicate "..." variable". The format string accepts the following specifiers, evaluated in the same local time zone as [$time_local](#v-time-local): | `%Y` | 4-digit year | |------------|--------------------------------------------| | `%y` | 2-digit year | | `%m` | month, `01-12` | | `%d` | day of month, `01-31` | | `%e` | day of month, space-padded, `1-31` | | `%H` | hour, `00-23` | | `%I` | hour, `01-12` | | `%M` | minute, `00-59` | | `%S` | second, `00-59` | | `%L` | milliseconds, `000-999` | | `%p` | uppercase `AM` / `PM` | | `%P` | lowercase `am` / `pm` | | `%a` | abbreviated weekday name, `Sun-Sat` | | `%A` | full weekday name, `Sunday-Saturday` | | `%b`, `%h` | abbreviated month name, `Jan-Dec` | | `%B` | full month name, `January-December` | | `%z` | time zone offset, `+0300` | | `%Z` | time zone offset, ISO 8601 style, `+03:00` | | `%n` | newline | | `%t` | tab | | `%%` | literal `%` | #### NOTE An unrecognized specifier is copied to the output verbatim, including the leading `%`; a standalone `%` at the very end of the format string is dropped. ### try_files | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `try_files` file ... uri;

`try_files` file ... =code; | |------------------------------------------------------------------------------------------|------------------------------------------------------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | server, location | Checks the existence of files in the specified order and uses the first found file for request processing; the processing is performed in the current [location](#location)'s context. The path to a file is constructed from the file parameter according to the [root](#root) and [alias](#alias) directives. It is possible to check directory's existence by specifying a slash at the end of a name, e.g. `$uri/`. If none of the files were found, an internal redirect to the uri specified in the last parameter is made. The file and uri parameters can contain variables. For example: ```nginx location /images/ { try_files $uri /images/default.gif; } location = /images/default.gif { expires 30s; } ``` The last parameter can be a URI for an internal redirect, a reference to a named `location` (e.g., `@drupal`), or a response code in the form `=code` (e.g., `=404`): ```nginx location / { try_files $uri $uri/index.html $uri.html =404; } ``` It should be noted that excessive use of the `try_files` directive increases the number of system calls, which can negatively impact performance. Thus, `try_files` should not be used to replicate behavior that is effectively the default behavior, for example: ```nginx location /bad_pattern { # try_files $uri $uri/ =404; # not recommended! } ``` Also, `try_files` should not be used solely for redirecting when a file is absent. The reason is that the `try_files` directive has two peculiarities: - First, it checks the existence of each file, which increases system load. - Second, any file opening errors (e.g., `too many open files`, permission errors) are also treated as file absence and trigger a fallback to the backup handler, which can mask 5xx errors with successful responses and lead to incorrect caching. Thus, in practice, the following problematic construction can be encountered: ```nginx location / { try_files $uri $uri/ @drupal; # not recommended! } ``` The problem here is that the only purpose is redirection. Using `try_files` leads to the disadvantages listed above, but provides no benefits, since checking for file existence is not needed. The correct solution is to use the [error_page](#error-page) directive, which does not have these disadvantages: ```nginx error_page 404 = @drupal; log_not_found off; ``` In contrast, in the following example: ```nginx location ~ \.php$ { try_files $uri @drupal; fastcgi_pass ...; fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; # ... } ``` The `try_files` directive checks for the existence of the PHP file before passing the request to the FastCGI server configured in the same block; here the use of `try_files` is justified. ### Example of use when proxying to Mongrel: ```nginx location / { try_files /system/maintenance.html $uri $uri/index.html $uri.html @mongrel; } location @mongrel { proxy_pass http://mongrel; } ``` ### Example of use with Drupal/FastCGI: ```nginx location / { error_page 404 = @drupal; } location ~ \.php$ { try_files $uri @drupal; fastcgi_pass ...; fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; fastcgi_param SCRIPT_NAME $fastcgi_script_name; fastcgi_param QUERY_STRING $args; # ... other fastcgi_param } location @drupal { fastcgi_pass ...; fastcgi_param SCRIPT_FILENAME /path/to/index.php; fastcgi_param SCRIPT_NAME /index.php; fastcgi_param QUERY_STRING q=$uri&$args; # ... other fastcgi_param } ``` ### Example of use with Wordpress and Joomla: ```nginx location / { error_page 404 = @wordpress; } location ~ \.php$ { try_files $uri @wordpress; fastcgi_pass ...; fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; # ... other fastcgi_param } location @wordpress { fastcgi_pass ...; fastcgi_param SCRIPT_FILENAME /path/to/index.php; # ... other fastcgi_param } ``` ### types | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `types` { ... } | |------------------------------------------------------------------------------------------|------------------------------------------------------------| | Default | `types *text/html html; image/gif gif; image/jpeg jpg;* ` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Maps file name extensions to MIME types of responses. Extensions are case-insensitive. Several extensions can be mapped to one type, for example: ```nginx types { application/octet-stream bin exe dll; application/octet-stream deb; application/octet-stream dmg; } ``` A sufficiently complete mapping table is distributed with Angie and is located in the `conf/mime.types` file. To make a particular `location` return the "application/octet-stream" MIME type for all responses, the following configuration can be used: ```nginx location /download/ { types { } default_type application/octet-stream; } ``` ### types_hash_bucket_size | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `types_hash_bucket_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units); | |------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------| | Default | `types_hash_bucket_size 64;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Sets the bucket size for the types hash tables. The details of setting up hash tables are discussed [separately](https://en.angie.software//angie/docs/configuration/configfile.md#configure-hashes). ### types_hash_max_size | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `types_hash_max_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units); | |------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------| | Default | `types_hash_max_size 1024;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Sets the maximum size of the types hash tables. The details of setting up hash tables are discussed [separately](https://en.angie.software//angie/docs/configuration/configfile.md#configure-hashes). ### underscores_in_headers | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `underscores_in_headers` `on` | `off`; | |------------------------------------------------------------------------------------------|------------------------------------------| | Default | `underscores_in_headers off`; | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server | Enables or disables the use of underscores in client request header fields. When the use of underscores is disabled, request header fields whose names contain underscores are marked as invalid and are subject to the [ignore_invalid_headers](#ignore-invalid-headers) directive. If the directive is specified at the [server](#server) level, the value from the default server can be used. ### variables_hash_bucket_size | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `variables_hash_bucket_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units); | |------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------| | Default | `variables_hash_bucket_size 64;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http | Sets the bucket size for the variables hash table. The details of setting up hash tables are discussed [separately](https://en.angie.software//angie/docs/configuration/configfile.md#configure-hashes). ### variables_hash_max_size #### Versionchanged Changed in version 1.11.0. | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `variables_hash_max_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units); | |------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------| | Default | `variables_hash_max_size 2048;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http | Sets the maximum size of the variables hash table. The details of setting up hash tables are discussed [separately](https://en.angie.software//angie/docs/configuration/configfile.md#configure-hashes). ## Built-in Variables The `http_core` module supports built-in variables with names matching the Apache Server variables. First of all, these are variables representing client request header fields, such as `$http_user_agent`, `$http_cookie`, and so on. Also, there are other variables: ### `$angie_version` Angie version ### `$arg_` argument name in the request line ### `$args` arguments in the request line ### `$binary_remote_addr` client address in a binary form, value's length is always 4 bytes for IPv4 addresses or 16 bytes for IPv6 addresses ### `$body_bytes_sent` number of bytes sent to the client, not counting the response header; this variable is compatible with the "%B" parameter of the `mod_log_config` Apache module ### `$bytes_sent` number of bytes sent to a client ### `$connection` connection serial number ### `$connection_requests` current number of requests made through a connection ### `$connection_time` connection time in seconds with a milliseconds resolution ### `$content_length` `Content-Length` request header field ### `$content_type` `Content-Type` request header field ### `$cookie_` cookie with the specified name ### `$document_root` [root](#root) or [alias](#alias) directive's value for the current request ### `$document_uri` same as [$uri](#v-uri) ### `$host` in this order of precedence: host name from the request line, or host name from the "Host" request header field, or the server name matching a request ### `$hostname` host name ### `$http_` #### Versionchanged Changed in version 1.11.0: In HTTP/3 requests, `$http_host` is initialized from the `:authority` pseudo-header if the `Host` header was not passed by the client. arbitrary request header field; the last part of the variable name corresponds to the field name converted to lower case with dashes replaced by underscores ### `$https` `on` if connection operates in SSL mode, or an empty string otherwise ### `$is_args` `?` if a request line has arguments, or an empty string otherwise ### `$is_request_port` `:` if the [$request_port](#v-request-port) value is non-empty, or an empty string otherwise ### `$limit_rate` setting this variable enables response rate limiting; see [limit_rate](#limit-rate) ### `$msec` current time in seconds with the milliseconds resolution ### `$nginx_version` nginx version ### `$pid` PID of the worker process ### `$pipe` `p` if request was pipelined, `.` otherwise ### `$proxy_protocol_addr` client address from the PROXY protocol header The PROXY protocol must be previously enabled by setting the `proxy_protocol` parameter in the [listen](#listen) directive. ### `$proxy_protocol_port` client port from the PROXY protocol header The PROXY protocol must be previously enabled by setting the `proxy_protocol` parameter in the [listen](#listen) directive. ### `$proxy_protocol_server_addr` server address from the PROXY protocol header The PROXY protocol must be previously enabled by setting the `proxy_protocol` parameter in the [listen](#listen) directive. ### `$proxy_protocol_server_port` server port from the PROXY protocol header The PROXY protocol must be previously enabled by setting the `proxy_protocol` parameter in the [listen](#listen) directive. ### `$proxy_protocol_tlv_` TLV from the PROXY protocol header. The name can be a TLV type name or its numeric value. In the latter case, the value is hexadecimal and should be prefixed with `0x`: ```none $proxy_protocol_tlv_alpn $proxy_protocol_tlv_0x01 ``` SSL TLVs can also be accessed by TLV type name or its numeric value, both prefixed by `ssl_`: ```none $proxy_protocol_tlv_ssl_version $proxy_protocol_tlv_ssl_0x21 ``` The following TLV type names are supported: * `alpn (0x01)` - upper layer protocol used over the connection * `authority (0x02)` - host name value passed by the client * `unique_id (0x05)` - unique connection id * `netns (0x30)` - name of the namespace * `ssl (0x20)` - binary SSL TLV structure The following SSL TLV type names are supported: * `ssl_version (0x21)` - SSL version used in client connection * `ssl_cn (0x22)` - SSL certificate Common Name * `ssl_cipher (0x23)` - name of the used cipher * `ssl_sig_alg (0x24)` - algorithm used to sign the certificate * `ssl_key_alg (0x25)` - public-key algorithm Also, the following special SSL TLV type name is supported: * `ssl_verify` - client SSL certificate verification result: `0` if the client presented a certificate and it was successfully verified, non-zero otherwise The PROXY protocol must be previously enabled by setting the `proxy_protocol` parameter in the [listen](#listen) directive. ### `$query_string` same as [$args](#v-args) ### `$realpath_root` an absolute pathname corresponding to the [root](#root) or [alias](#alias) directive's value for the current request, with all symbolic links resolved to real paths ### `$remote_addr` client address ### `$remote_port` client port ### `$remote_user` user name supplied with the Basic authentication ### `$request` full original request line ### `$request_body` request body The variable's value is *made available* in locations processed by the [proxy_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass), [fastcgi_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-pass), [uwsgi_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-pass), and [scgi_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-pass) directives when the request body was read to a [memory buffer](#client-body-buffer-size). ### `$request_body_file` name of a temporary file with the request body At the end of processing, the file needs to be removed. To always write the request body to a file, enable [client_body_in_file_only](#client-body-in-file-only). When passing the name of a temporary file in a proxied request or in a request to a FastCGI/uwsgi/SCGI server, the passing of the request body itself should be disabled with the [proxy_pass_request_body off](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass-request-body), [fastcgi_pass_request_body off](https://en.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-pass-request-body), [uwsgi_pass_request_body off](https://en.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-pass-request-body), or [scgi_pass_request_body off](https://en.angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-pass-request-body) directives, respectively. ### `$request_completion` `OK` if a request has completed, or an empty string otherwise ### `$request_filename` file path for the current request, based on the [root](#root) or [alias](#alias) directives, and the request URI ### `$request_id` unique request identifier generated from 16 random bytes, in hexadecimal ### `$request_length` request length in bytes (including request line, header, and request body) ### `$request_method` request method, usually `GET` or `POST` ### `$request_port` in this order of precedence: port number from the authority component of the request URI, or port number from the "Host" request header field ### `$request_time` request processing time in seconds with a milliseconds resolution; time elapsed since the first bytes were read from the client ### `$request_uri` full original request URI (with arguments), never modified during request processing; see [$uri](#v-uri) for the current (potentially rewritten) URI ### `$scheme` request scheme, "http" or "https" ### `$sent_body` #### Versionadded Added in version 1.11.0. response body of a subrequest or external request when it is stored in memory; otherwise an empty string ### `$sent_http_` arbitrary response header field; the last part of the variable name corresponds to the field name converted to lower case with dashes replaced by underscores ### `$sent_trailer_` arbitrary field sent at the end of the response; the last part of the variable name corresponds to the field name converted to lower case with dashes replaced by underscores ### `$server_addr` address of the server which accepted a request Computing a value of this variable usually requires one system call. To avoid a system call, the [listen](#listen) directives must specify addresses and use the `bind` parameter. ### `$server_name` name of the server which accepted a request ### `$server_port` port of the server which accepted a request ### `$server_protocol` request protocol, usually "HTTP/1.0", "HTTP/1.1", or "HTTP/2.0" ### `$status` response status ### `$tcpinfo_rtt, $tcpinfo_rttvar, $tcpinfo_snd_cwnd, $tcpinfo_rcv_space` information about the client TCP connection; available on systems that support the `TCP_INFO` socket option; on Linux, `$tcpinfo_rtt` and `$tcpinfo_rttvar` are in microseconds, `$tcpinfo_snd_cwnd` is a number of segments, and `$tcpinfo_rcv_space` is in bytes ### `$time_iso8601` local time in the ISO 8601 standard format ### `$time_local` local time in the Common Log Format ### `$uri` current URI in request, [normalized](#location) The value of `$uri` may change during request processing, e.g. when rewriting with [rewrite](https://en.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#id5), when doing internal redirects, or when using index files. See [Choosing locations](https://en.angie.software//angie/docs/configuration/processing.md#pick-location) for how the value is mapped to a filesystem path. # https://en.angie.software/angie/docs/configuration/modules/http/http_access.md # Access The module controls access to server resources based on client IP addresses or networks. It allows permitting or blocking access for specific IP addresses, IP ranges, or UNIX domain sockets to enhance security by restricting access to sensitive areas of a website or application. Access can also be restricted by using a password with the [Auth Basic](https://en.angie.software//angie/docs/configuration/modules/http/http_auth_basic.md#http-auth-basic) module or based on the result of a subrequest with the [Auth Request](https://en.angie.software//angie/docs/configuration/modules/http/http_auth_request.md#http-auth-request) module. To apply both address and password restrictions at the same time, use the [satisfy](https://en.angie.software//angie/docs/configuration/modules/http/index.md#satisfy) directive. When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by default; it can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure) `--without-http_access_module`. In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the module is included in the build. ## Configuration Example ```nginx location / { deny 192.168.1.1; allow 192.168.1.0/24; allow 10.1.1.0/16; allow 2001:0db8::/32; deny all; } ``` Rules are evaluated sequentially until a match is found. In this example, access is allowed only for the IPv4 networks `10.1.1.0/16` and `192.168.1.0/24`, excluding the specific address `192.168.1.1`, and for the IPv6 network `2001:0db8::/32`. When there are many rules, it is preferable to use variables from the [Geo](https://en.angie.software//angie/docs/configuration/modules/http/http_geo.md#http-geo) module. ## Directives ### allow | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `allow` address | CIDR | `unix:` | `all`; | |------------------------------------------------------------------------------------------|---------------------------------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, limit_except | Allows access for a specified network or address. The special value `all` means all client IP addresses. The special value `unix:` allows access for any UNIX domain sockets. ### deny | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `deny` address | CIDR | `unix:` | `all`; | |------------------------------------------------------------------------------------------|--------------------------------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, limit_except | Denies access for a specified network or address. The special value `all` means all client IP addresses. The special value `unix:` denies access for any UNIX domain sockets. # https://en.angie.software/angie/docs/configuration/modules/http/http_acme.md # ACME Provides automatic certificate retrieval using the [ACME protocol](https://datatracker.ietf.org/doc/html/rfc8555). When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module isn't built by default; it must be enabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure) `--with-http_acme_module`. In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the module is included in the build. ## Configuration Example In this example, an ACME client named `example` automatically obtains and renews a certificate for `example.com` and `www.example.com` using the default HTTP validation: ```nginx http { resolver 127.0.0.53; # Required for the 'acme_client' directive acme_client example https://acme-v02.api.letsencrypt.org/directory; server { listen 80; # Optional if no server listens on the HTTP challenge port # (see 'acme_http_port' directive) listen 443 ssl; server_name example.com www.example.com; acme example; ssl_certificate $acme_cert_example; ssl_certificate_key $acme_cert_key_example; } } ``` For other validation methods (DNS, ALPN, hook-based) and detailed setup instructions, see the [ACME Configuration](https://en.angie.software//angie/docs/configuration/acme.md#acme-config) section. ## Directives ### acme | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `acme` name; | |------------------------------------------------------------------------------------------|----------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | server | Specifies the [ACME client](#acme-client) that obtains a certificate for the valid certificate identifiers in this [server](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server) block. A single certificate covers all valid domain names and IP addresses specified in the [server_name](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server-name) directives of every [server](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server) block that references the client with the given name; if the `server_name` configuration changes, the certificate is renewed to reflect the changes. Each time Angie starts or reloads its configuration, new certificates are requested for all identifiers that are missing a valid certificate. Possible reasons include certificate expiration, missing or unreadable files, a change in certificate settings, or a previous request that ended in an error. #### NOTE This directive only controls which valid certificate identifiers are included in certificate requests; it does not affect where the certificate can be used. Any `server` block can reference the certificate through the [$acme_cert_](#v-acme-cert-name) variable, regardless of whether the block contains an `acme` directive. Removing `acme` from a `server` block simply excludes that block's [server_name](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server-name) values from future certificate requests, but does not prevent the block from using the certificate. #### NOTE Currently, domains specified with regular expressions are not supported and will be skipped. Wildcard domains are supported only with `challenge=dns` in `acme_client`. IPv4 and IPv6 addresses are supported unless the client uses `challenge=dns`. With DNS validation enabled, IP addresses are skipped. This directive can be specified multiple times to load certificates of different types, for example RSA and ECDSA: ```nginx server { listen 443 ssl; server_name example.com www.example.com; ssl_certificate $acme_cert_rsa; ssl_certificate_key $acme_cert_key_rsa; ssl_certificate $acme_cert_ecdsa; ssl_certificate_key $acme_cert_key_ecdsa; acme rsa; acme ecdsa; } ``` ### acme_client #### Versionchanged Changed in version 1.11.0. #### Versionchanged Changed in version 1.12.0. | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `acme_client` name uri [`enabled=``on` | `off`] [`key_type=`type] [`key_bits=`number] [`email=`email] [`max_cert_size=`size] [`max_key_auth_size=`size] [`renew_before_expiry=`time] [`renew_on_load`] [`retry_after_error=`off|time] [`challenge=``dns` | `http` | `alpn`] [`profile=`name] [`account_key=`file] [`eab=`id[:alg]:key]; | |------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http | Defines an ACME client with a globally unique name. It must be valid for a directory, is a [string with variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables), and will be used case-insensitively. Each client manages a single certificate; to obtain separate certificates, configure multiple `acme_client` blocks (see [Separate Certificates for Different Domains](https://en.angie.software//angie/docs/configuration/acme.md#acme-config-multiple-clients)). The second mandatory parameter is the uri of the ACME directory. For example, the Let's Encrypt ACME directory URI is [specified](https://letsencrypt.org/getting-started/) as [https://acme-v02.api.letsencrypt.org/directory](https://acme-v02.api.letsencrypt.org/directory). #### NOTE The ACME module adds a named `location @acme` to the [client](https://en.angie.software//angie/docs/configuration/modules/http/index.md#client) context, which can be used to configure requests to the ACME directory; by default, this `location` contains a [proxy_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass) directive with the directory uri, to which other settings from the [Proxy](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy) module can be added. For this directive to work, a [resolver](https://en.angie.software//angie/docs/configuration/modules/http/index.md#resolver) must be configured in the same context. #### NOTE For testing purposes, certificate authorities usually provide separate staging environments. For example, the [Let's Encrypt staging environment](https://letsencrypt.org/docs/staging-environment/) is [https://acme-staging-v02.api.letsencrypt.org/directory](https://acme-staging-v02.api.letsencrypt.org/directory). | `enabled` | Enables or disables certificate renewal for the client;
this is useful, for example, for temporarily suspending
without removing the client from the configuration.

Default: `on`. | |-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `key_type` | The type of private key algorithm for the certificate.
Valid values: `rsa`, `ecdsa`.

Default: `ecdsa`. | | `key_bits` | Number of bits in the certificate key.
Default: 256 for `ecdsa`, 2048 for `rsa`. | | `email` | Optional email address for feedback;
used when creating an account on the CA server. | | `max_cert_size` | Specifies the maximum allowed size of a new certificate file
to reserve space for the new certificate in shared memory;
the more domains the certificate is requested for,
the more space is required.
The size is specified in bytes;
the `k` and `m` suffixes are also accepted.
This parameter does not limit the size of ACME server responses;
use [acme_max_response_size](#acme-max-response-size) for that.

If the parameter is not set, Angie calculates an approximate size
based on the configured domain list and uses it for shared memory
allocation.

If a certificate already exists at startup but its size exceeds the
`max_cert_size` value, the `max_cert_size` value is
dynamically increased to match the size of the existing certificate
file.

If the size of a certificate obtained during renewal
exceeds `max_cert_size`,
the renewal process will fail with an error.

Default: calculated automatically. | | `max_key_auth_size` | Limits the size of the key authorization string
that Angie stores in shared memory for an ACME challenge.
If the ACME server returns a key authorization string
larger than this value, the request fails with an error
that advises raising `max_key_auth_size`.

Although specified on the `acme_client` line,
this is a single setting shared by all clients
in the `http` block.

Default: `2k`. | | `renew_before_expiry` | [Time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units) before certificate expiration
when renewal should begin.

Default: `30d`. | | `renew_on_load` | Specifies that the certificate should be forcibly renewed
each time the configuration is loaded. | | `retry_after_error` | [Time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units) to wait before retrying
if certificate retrieval failed.
If set to `off`,
the client will not retry to obtain the certificate after an error.

Default: `2h`.

This delay applies while Angie is running;
a configuration reload re-requests the certificate immediately. | | `challenge` | Specifies the verification type for the ACME client.
Valid values: `dns`, `http`, `alpn`.

The `alpn` value enables [TLS-ALPN-01](https://datatracker.ietf.org/doc/rfc8737/) validation and requires
Angie to be built with OpenSSL that supports ALPN
(not supported with BoringSSL or AWS-LC builds).

Default: `http`. | | `profile` | Requests a specific ACME profile from the certificate authority.
A profile is a CA-defined variant of the certificate and validation
settings, for example the certificate lifetime
or which identifier types may be requested.

For instance, Let's Encrypt describes its available profiles in the
[profiles documentation](https://letsencrypt.org/docs/profiles/).

The ACME server must advertise this profile in its directory metadata;
otherwise the client cannot obtain a certificate. | | `account_key` | Specifies the full path to a file containing a key in PEM format.
This is useful if you want to use an existing account key
instead of automatic generation,
or if you need to use one key for multiple ACME clients.

Supported key types:

- RSA keys with lengths that are multiples of 8, ranging from 2048 to 8192 bits.
- ECDSA keys with lengths of 256, 384, or 521 bits.

When specifying the `account_key` parameter,
ensure that the key file actually exists.
If the file is missing,
Angie will attempt to create it at the specified path.

Note that keys for ACME clients are created in the order
the corresponding clients are mentioned in the configuration
in [acme_client](#acme-client), [acme](#id1), or [acme_hook](#acme-hook) directives.
Therefore, if one client should use a key
created for another,
that other client must appear earlier in the configuration.

Additionally, keys are only created for clients
that have the `enabled=on` parameter set. | | `eab` | Configures [External Account Binding](https://datatracker.ietf.org/doc/html/rfc8555#section-7.3.4) (EAB),
binding the ACME account to an account already registered with the
certificate authority (CA).

The value has the form `eab=`id[:alg]:key:

- id — the key identifier issued by the CA.
- alg — the HMAC signing algorithm used to compute the binding
signature: `HS256` (default), `HS384`, or `HS512`.
- key — the Base64URL-encoded MAC key associated with id on the
CA side.

If the CA requires external account binding but the parameter is not
set, the client reports an error without creating an ACME account. The
EAB credentials are only sent when a new ACME account is registered; an
existing ACME account is reused as is. | ### acme_client_path | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `acme_client_path` path; | |------------------------------------------------------------------------------------------|----------------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http | Overrides the path to the directory for storing certificates and keys, set during build using the [build parameter](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure) `--http-acme-client-path`. ### acme_dns_port | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `acme_dns_port` port | ip[:port] | [ip6][:port]; | |------------------------------------------------------------------------------------------|----------------------------------------------------| | Default | `acme_dns_port 53;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http | Specifies the port that the module uses to handle DNS queries from the ACME server over UDP. The port number must be in the range from 1 to 65535. Specifying an IP address along with an optional port is also supported. Both IPv4 addresses in the form `ip:port` and IPv6 addresses in the form `[ip6]:port` can be used: ```nginx acme_dns_port 8053; acme_dns_port 127.0.0.1; acme_dns_port [::1]; ``` To use port number 1024 or lower, Angie's master process must run with superuser privileges. ### acme_dns_ttl #### Versionadded Added in version 1.12.0. | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `acme_dns_ttl` number; | |------------------------------------------------------------------------------------------|--------------------------| | Default | `acme_dns_ttl 1;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http | Sets the TTL, in seconds, of the TXT records the module returns in responses to ACME servers' [DNS validation](https://en.angie.software//angie/docs/configuration/acme.md#acme-config-dns) queries. Accepts values from 0 through 2147483647, as per [RFC 2181](https://datatracker.ietf.org/doc/html/rfc2181#section-8). ### acme_hook | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `acme_hook` name [uri]; | |------------------------------------------------------------------------------------------|---------------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | location | Enables hook-based domain validation for the [ACME client](#acme-client) specified by name. When certificate issuance or renewal requires domain verification, Angie generates an internal request to the named `location` where this directive is placed. How the request is handled depends entirely on the other directives configured in the same `location`, such as [fastcgi_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-pass), [proxy_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass), or any other request handler. | name | The name of the [ACME client](#acme-client)
for which this hook handles domain verification. | |--------|----------------------------------------------------------------------------------------------------| | uri | A string with variables;
specifies the request URI for hook calls.

Default: `/`. | For example, the following configuration passes the values of [hook variables](#http-acme-variables) to a FastCGI application through the request URI: ```nginx acme_hook example uri=/acme_hook/$acme_hook_name?domain=$acme_hook_domain&key=$acme_hook_keyauth; fastcgi_param REQUEST_URI $request_uri; fastcgi_pass ...; ``` ### acme_http_port #### Versionadded Added in version 1.11.0. #### Versionchanged Changed in version 1.11.1. | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `acme_http_port` port | ip[:port] | [ip6][:port]; | |------------------------------------------------------------------------------------------|-----------------------------------------------------| | Default | `acme_http_port 80;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http | Specifies the port that the module uses to handle HTTP ACME challenge requests. The port number must be in the range from 1 to 65535. Specifying an IP address along with an optional port is also supported. Both IPv4 addresses in the form `ip:port` and IPv6 addresses in the form `[ip6]:port` can be used: ```nginx acme_http_port 8080; acme_http_port 127.0.0.1; acme_http_port [::1]; ``` If no server is configured to listen on the specified address and port, the module creates a dedicated listener for HTTP challenges. To use port number 1024 or lower, Angie's master process must run with superuser privileges. ### acme_max_response_size #### Versionadded Added in version 1.11.0. | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `acme_max_response_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units); | |------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------| | Default | `acme_max_response_size 32k;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http | Limits the maximum size of an ACME server response body. If a response exceeds this limit, the request fails with an error. Increase the value if you see errors like `too big subrequest response while sending to client`. ## Built-in Variables ### `$acme_cert_` Contents of the last certificate file (if any) obtained by the client with this name. ### `$acme_cert_key_` Contents of the certificate key file used by the client with this name. #### NOTE The certificate file is available only if the ACME client has obtained at least one certificate, but the key file is available immediately after startup. ### `$acme_hook_challenge` The challenge type. Possible values: `dns`, `http`, `alpn`. ### `$acme_hook_client` The name of the ACME client initiating the request. ### `$acme_hook_domain` The domain being verified. If it is a wildcard domain, it will be passed without the `*.` prefix. ### `$acme_hook_keyauth` The authorization string: - For DNS challenge, it is used as the value of the TXT record, whose name is formed as `_acme-challenge. + $acme_hook_domain + .`. - For HTTP challenge, this string must be used as the content of the response requested by the ACME server. ### `$acme_hook_name` The hook name. For different challenge types, it may have different values and meanings: | Value | Meaning for DNS challenge | Meaning for HTTP challenge | |--------------------------|----------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------| | `add` (adding hook) | The corresponding TXT record must be added to the DNS configuration. | A response to the corresponding HTTP request must be prepared. | | `remove` (removing hook) | The TXT record can be removed from the DNS configuration. | This HTTP request is no longer relevant;
the previously created file with the authorization string can be removed. | ### `$acme_hook_token` The verification token. For HTTP challenge, it is used as the name of the requested file: `/.well-known/acme-challenge/` + `$acme_hook_token`. # https://en.angie.software/angie/docs/configuration/modules/http/http_addition.md # Addition The module is a filter that adds text before and after a response. When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module isn't built by default; it must be enabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure) `--with-http_addition_module`. In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the module is included in the build. ## Configuration Example ```nginx location / { add_before_body /before_action; add_after_body /after_action; } ``` ## Directives ### add_after_body | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `add_after_body` uri; | |------------------------------------------------------------------------------------------|-------------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Adds the text returned as a result of processing a given subrequest after the response body. An empty string (`""`) as a parameter cancels addition inherited from the previous configuration level. ### add_before_body | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `add_before_body` uri; | |------------------------------------------------------------------------------------------|--------------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Adds the text returned as a result of processing a given subrequest before the response body. An empty string (`""`) as a parameter cancels addition inherited from the previous configuration level. ### addition_types | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `addition_types` mime-type ...; | |------------------------------------------------------------------------------------------|-----------------------------------| | Default | `addition_types text/html;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | Allows adding text in responses with the specified MIME types, in addition to "text/html". The special value "\*" matches any MIME type. # https://en.angie.software/angie/docs/configuration/modules/http/http_api.md # API The `API` module implements an HTTP RESTful interface for obtaining basic information about the web server in JSON format, as well as [statistics](#metrics) on client connections, shared memory zones, DNS queries, HTTP requests, HTTP response cache, [Stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) module sessions, and zones of the HTTP [Limit Conn](https://en.angie.software//angie/docs/configuration/modules/http/http_limit_conn.md#http-limit-conn), Stream [Limit Conn](https://en.angie.software//angie/docs/configuration/modules/stream/stream_limit_conn.md#stream-limit-conn), [Limit Req](https://en.angie.software//angie/docs/configuration/modules/http/http_limit_req.md#http-limit-req), and HTTP [Upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream) modules, as well as information about certificates specified in the configuration and obtained by ACME clients. #### NOTE Explore a live example of the API output at [https://console.angie.software/api/](https://console.angie.software/api/). The interface accepts `GET` and `HEAD` HTTP methods; a request with another method will cause an error: ```json { "error": "MethodNotAllowed", "description": "The POST method is not allowed for the requested API element \"/\"." } ``` In Angie PRO, this interface includes a [dynamic configuration](#api-config) section that allows changing settings without reloading the configuration or restarting; currently, configuration of individual servers within [upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) is available. When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by default; it can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure) `--without-http_api_module`. In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the module is included in the build. ## Directives ### api | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `api` path; | |------------------------------------------------------------------------------------------|---------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | location | Enables the HTTP RESTful interface in `location`. The path parameter is mandatory. Similar to the [alias](https://en.angie.software//angie/docs/configuration/modules/http/index.md#alias) directive, it sets the path for replacing the one specified in `location`, but over the API tree rather than the filesystem. If specified in a prefix `location`: ```nginx location /stats/ { api /status/http/server_zones/; } ``` the part of the request URI matching the prefix /stats/ will be replaced with the path specified in the path parameter: /status/http/server_zones/. For example, a request to /stats/foo/ will access the API element `/status/http/server_zones/foo/`. [Variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables) are allowed: api /status/$module/server_zones/$name/ and usage inside regex location: ```nginx location ~^/api/([^/]+)/(.*)$ { api /status/http/$1_zones/$2; } ``` Here the path parameter defines the full path to the API element; thus, from a request to `/api/location/data/` the following variables will be extracted: ```console $1 = "location" $2 = "data/" ``` And the final request will be `/status/http/location_zones/data/`. #### NOTE In Angie PRO, you can separate the [dynamic configuration API](#api-config) and the immutable [status API](#metrics) that reflects the current state: ```nginx location /config/ { api /config/; } location /status/ { api /status/; } ``` The path parameter also allows controlling API access: ```nginx location /status/ { api /status/; allow 127.0.0.1; deny all; } ``` Or: ```nginx location /blog/requests/ { api /status/http/server_zones/blog/requests/; auth_basic "blog"; auth_basic_user_file conf/htpasswd; } ``` #### NOTE If `api` is placed in a `location` with a trailing slash in the prefix (for example, `location /name/`), and the [auto_redirect](https://en.angie.software//angie/docs/configuration/modules/http/index.md#auto-redirect) directive is set to `default`, requests without a trailing slash will be redirected (`/name -> /name/`). ### api_config_files | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `api_config_files` `on` | `off`; | |------------------------------------------------------------------------------------------|------------------------------------| | Default | off | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | location | Enables or disables adding the `config_files` object, which lists the contents of all Angie configuration files currently loaded by the server instance, to the [/status/angie/](#status-angie) API section. For example, with this configuration: ```nginx location /status/ { api /status/; api_config_files on; } ``` A request to `/status/angie/` returns approximately the following: ```json { "version":"1.12.1", "address":"192.168.16.5", "generation":1, "load_time":"2026-07-17T12:58:39.789Z", "config_files": { "/etc/angie/angie.conf": "...", "/etc/angie/mime.types": "..." } } ``` By default, output is disabled because configuration files may contain particularly sensitive, confidential information. ## Metrics Angie publishes usage statistics in the `/status/` API section; you can open access to it by setting the appropriate `location`. Full access: ```nginx location /status/ { api /status/; } ``` Example of partial access, already shown above: ```nginx location /stats/ { api /status/http/server_zones/; } ``` ### Example configuration With a configuration including `location /status/`, `resolver`, `http` in `upstream`, `http server`, `location`, `cache`, `limit_conn` in `http` and `limit_req` zones: ```nginx http { resolver 127.0.0.53 status_zone=resolver_zone; proxy_cache_path /var/cache/angie/cache keys_zone=cache_zone:2m; limit_conn_zone $binary_remote_addr zone=limit_conn_zone:10m; limit_req_zone $binary_remote_addr zone=limit_req_zone:10m rate=1r/s; upstream upstream { zone upstream 256k; server backend.example.com service=_example._tcp resolve max_conns=5; keepalive 4; } server { server_name www.example.com; listen 443 ssl; status_zone http_server_zone; proxy_cache cache_zone; proxy_cache_valid 200 10m; access_log /var/log/access.log main; location / { root /usr/share/angie/html; status_zone location_zone; limit_conn limit_conn_zone 1; limit_req zone=limit_req_zone burst=5; } location /status/ { api /status/; allow 127.0.0.1; deny all; } } } ``` In response to the request `curl https://www.example.com/status/`, Angie returns: ### JSON tree ```json { "angie": { "version":"1.12.1", "address":"192.168.16.5", "generation":1, "load_time":"2026-07-17T12:58:39.789Z" }, "connections": { "accepted":2257, "dropped":0, "active":3, "idle":1 }, "slabs": { "cache_zone": { "pages": { "used":2, "free":506 }, "slots": { "64": { "used":1, "free":63, "reqs":1, "fails":0 }, "512": { "used":1, "free":7, "reqs":1, "fails":0 } } }, "limit_conn_zone": { "pages": { "used":2, "free":2542 }, "slots": { "64": { "used":1, "free":63, "reqs":74, "fails":0 }, "128": { "used":1, "free":31, "reqs":1, "fails":0 } } }, "limit_req_zone": { "pages": { "used":2, "free":2542 }, "slots": { "64": { "used":1, "free":63, "reqs":1, "fails":0 }, "128": { "used":2, "free":30, "reqs":3, "fails":0 } } } }, "http": { "server_zones": { "http_server_zone": { "ssl": { "handshaked":4174, "reuses":0, "timedout":0, "failed":0 }, "requests": { "total":4327, "processing":0, "discarded":8 }, "responses": { "200":4305, "302":12, "404":4 }, "data": { "received":733955, "sent":59207757 } } }, "location_zones": { "location_zone": { "requests": { "total":4158, "discarded":0 }, "responses": { "200":4157, "304":1 }, "data": { "received":538200, "sent":177606236 } } }, "caches": { "cache_zone": { "size":0, "cold":false, "hit": { "responses":0, "bytes":0 }, "stale": { "responses":0, "bytes":0 }, "updating": { "responses":0, "bytes":0 }, "revalidated": { "responses":0, "bytes":0 }, "miss": { "responses":0, "bytes":0, "responses_written":0, "bytes_written":0 }, "expired": { "responses":0, "bytes":0, "responses_written":0, "bytes_written":0 }, "bypass": { "responses":0, "bytes":0, "responses_written":0, "bytes_written":0 } } }, "limit_conns": { "limit_conn_zone": { "passed":73, "skipped":0, "rejected":0, "exhausted":0 } }, "limit_reqs": { "limit_req_zone": { "passed":54816, "skipped":0, "delayed":65, "rejected":26, "exhausted":0 } }, "upstreams": { "upstream": { "peers": { "192.168.16.4:80": { "server":"backend.example.com", "service":"_example._tcp", "backup":false, "weight":5, "state":"up", "selected": { "current":2, "total":232 }, "max_conns":5, "responses": { "200":222, "302":12 }, "data": { "sent":543866, "received":27349934 }, "health": { "fails":0, "unavailable":0, "downtime":0, "header_time":21, "response_time":42 }, "sid":"" } }, "keepalive":2 } } }, "resolvers": { "resolver_zone": { "queries": { "name":442, "srv":2, "addr":0 }, "responses": { "success":440, "timedout":1, "format_error":0, "server_failure":1, "not_found":1, "unimplemented":0, "refused":1, "other":0 } } } } ``` A set of metrics can be requested by individual JSON branch by constructing the appropriate request. For example: ```console $ curl https://www.example.com/status/angie $ curl https://www.example.com/status/connections $ curl https://www.example.com/status/slabs $ curl https://www.example.com/status/slabs//slots $ curl https://www.example.com/status/slabs//slots/64 $ curl https://www.example.com/status/http/ $ curl https://www.example.com/status/http/acme_clients $ curl https://www.example.com/status/http/acme_clients/ $ curl https://www.example.com/status/http/metric_zones $ curl https://www.example.com/status/http/metric_zones//metrics $ curl https://www.example.com/status/http/server_zones $ curl https://www.example.com/status/http/server_zones/ $ curl https://www.example.com/status/http/server_zones//ssl ``` ### Query arguments The following query-string arguments modify the API's JSON responses: `pretty` : By default, the API formats JSON responses with indentation and line breaks. To get compact, single-line output, add `pretty=off` to the query string:
```console $ curl https://www.example.com/status/connections?pretty=off
{"accepted":2257,"dropped":0,"active":3,"idle":1} ``` `date` : By default, the module uses ISO 8601 format strings for dates; to use the integer UNIX epoch format instead, add `date=epoch` to the query string:
```console $ curl https://www.example.com/status/angie/load_time
"2024-03-31T23:59:59Z"
$ curl https://www.example.com/status/angie/load_time?date=epoch
1711929599 ```
The string form is always UTC and carries milliseconds only when they are non-zero. The epoch form is a whole number of seconds; milliseconds are never part of it. `defaults` (PRO) : You can obtain default parameter values with the `defaults=on` argument:
```console $ curl http://127.0.0.1/config/http/upstreams/backend/servers?defaults=on ```
```json { "backend.example.com": { "weight": 1, "max_conns": 5, "max_fails": 1, "fail_timeout": 10, "slow_start": 0, "backup": false, "down": false, "sid": "" } } ``` ### Server status #### `/status/angie` ```json { "version": "1.12.1", "build_time": "2026-07-17T16:05:43.805Z", "address": "192.168.16.5", "generation": 1, "load_time": "2026-07-17T16:15:43.805Z" "config_files": { "/etc/angie/angie.conf": "...", "/etc/angie/mime.types": "..." } } ``` | `version` | String; version of the running Angie web server | |----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `build` | String; particular build name if specified during compilation | | `build_time` | String; the build time of the Angie executable
in the [date](#api-date-format) format | | `address` | String; the address of the server that accepted the API request | | `generation` | Number; the generation of the currently loaded configuration,
counted from the last start of Angie | | `load_time` | String; time of the last configuration reload
in the [date](#api-date-format) format | | `config_files` | Object; its members are absolute pathnames
of all Angie configuration files
that are currently loaded by the server instance,
and their values are string representations of the files' contents,
for example:

```json
{
"/etc/angie/angie.conf": "server {\n listen 80;\n # ...\n\n}\n"
}
```

#### WARNING
The `config_files` object is available in `/status/angie/`
only if the
[api_config_files](#a-api-config-files)
directive is enabled. | #### `/status/angie/license` (PRO) #### Versionadded Added in version 1.11.0: PRO ```json { "path": "/etc/angie/license.pem", "status": "valid", "owner": "Example Corp", "days_left": 30, "since": "2026-01-01", "until": "2027-01-01", "limits": { "worker_processes": 16, "worker_connections": 65535 } } ``` | `path` | String; full path to the license file | |-------------|------------------------------------------------------------------------------------------------------------------------------------------------------------| | `status` | String; license status: `missing`, `invalid`, `valid`,
`grace`, `expired`, or `pending` | | `owner` | String; license owner from the certificate subject | | `days_left` | Number; days until the license changes state. A negative value means
the license has expired, and the value is the number of days since
expiration | | `since` | String; license validity start date | | `until` | String; license validity end date | | `limits` | Object; licensed limits for the current instance | ### Connections #### `/status/connections` ```json { "accepted": 2257, "dropped": 0, "active": 3, "idle": 1 } ``` | `accepted` | Number; the total number of accepted client connections | |--------------|-----------------------------------------------------------| | `dropped` | Number; the total number of dropped client connections | | `active` | Number; the current number of active client connections | | `idle` | Number; the current number of idle client connections | ### Shared memory zones with slab allocation #### `/status/slabs/` Usage statistics of shared memory zones that utilize [slab allocation](https://en.wikipedia.org/wiki/Slab_allocation). Any zone that uses slab allocation is reported, including those of [limit_conn](#limit-conn), [limit_req](#limit-req), and [HTTP cache](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache), as well as the shared memory zone of an [HTTP](#a-upstream) or [stream](#a-s-upstream) upstream: ```nginx limit_conn_zone $binary_remote_addr zone=limit_conn_zone:10m; limit_req_zone $binary_remote_addr zone=limit_req_zone:10m rate=1r/s; proxy_cache cache_zone; proxy_cache_valid 200 10m; ``` The specified shared memory zone will collect the following statistics: | `pages` | Object; memory pages statistics. A page here is a system memory page,
usually 4K | |-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `used` | Number; the number of currently used memory pages | | `free` | Number; the number of currently free memory pages | | `slots` | Object; memory slots statistics for each slot size. The `slots` object contains data for memory slot sizes (`8`, `16`, `32`, etc., up to half of the page size in bytes) | | `used` | Number; the number of currently used memory slots of specified size | | `free` | Number; the number of currently free memory slots of specified size | | `reqs` | Number; the total number of attempts to allocate memory of specified size | | `fails` | Number; the number of unsuccessful attempts to allocate memory of specified size | Example: ```json { "pages": { "used": 2, "free": 506 }, "slots": { "64": { "used": 1, "free": 63, "reqs": 1, "fails": 0 } } ``` ### DNS queries to resolver #### `/status/resolvers/` To collect resolver statistics, the [resolver](https://en.angie.software//angie/docs/configuration/modules/http/index.md#resolver) directive must set the `status_zone` parameter ([HTTP](https://en.angie.software//angie/docs/configuration/modules/http/index.md#resolver-status) or [Stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#s-resolver-status)): ```nginx resolver 127.0.0.53 status_zone=resolver_zone; ``` The specified shared memory zone will collect the following statistics: | `queries` | Object; queries statistics | |------------------|--------------------------------------------------------------------------------------| | `name` | Number; the number of queries to resolve names to addresses
(A and AAAA queries) | | `srv` | Number; the number of queries to resolve services to addresses
(SRV queries) | | `addr` | Number; the number of queries to resolve addresses to names
(PTR queries) | | `responses` | Object; responses statistics | | `success` | Number; the number of successful responses | | `timedout` | Number; the number of timed out queries | | `format_error` | Number; the number of responses with code 1 (Format Error) | | `server_failure` | Number; the number of responses with code 2 (Server Failure) | | `not_found` | Number; the number of responses with code 3 (Name Error) | | `unimplemented` | Number; the number of responses with code 4 (Not Implemented) | | `refused` | Number; the number of responses with code 5 (Refused) | | `other` | Number; the number of queries completed with other non-zero code | | `sent` | Object; sent DNS queries statistics | | `a` | Number; the number of A type queries | | `aaaa` | Number; the number of AAAA type queries | | `ptr` | Number; the number of PTR type queries | | `srv` | Number; the number of SRV type queries | #### NOTE `queries` and `responses` count every resolution request Angie makes internally, including those served from the TTL cache. `sent` counts packets actually dispatched to the name server; the gap between the two reflects cache hits. The response codes are described in [RFC 1035](https://datatracker.ietf.org/doc/html/rfc1035.html), section [4.1.1](https://datatracker.ietf.org/doc/html/rfc1035.html#section-4.1.1). Various DNS record types are detailed in [RFC 1035](https://datatracker.ietf.org/doc/html/rfc1035.html), [RFC 2782](https://datatracker.ietf.org/doc/html/rfc2782.html), and [RFC 3596](https://datatracker.ietf.org/doc/html/rfc3596.html). Example: ```json { "queries": { "name": 442, "srv": 2, "addr": 0 }, "responses": { "success": 440, "timedout": 1, "format_error": 0, "server_failure": 1, "not_found": 1, "unimplemented": 0, "refused": 1, "other": 0 }, "sent": { "a": 185, "aaaa": 245, "srv": 2, "ptr": 12 } } ``` ### HTTP server and location #### `/status/http/server_zones/` To collect the `server` metrics, set the [status_zone](https://en.angie.software//angie/docs/configuration/modules/http/index.md#status-zone) directive in the [server](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server) context: ```nginx server { ... status_zone server_zone; } ``` To group the metrics by a custom value, use the alternative syntax. Here, the metrics are aggregated by [$host](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-host), with each group reported as a standalone zone: ```nginx status_zone $host zone=server_zone:5; ``` The number after the zone name is a limit on groups, not a memory size (see [status_zone](https://en.angie.software//angie/docs/configuration/modules/http/index.md#status-zone)); metrics for values beyond the limit are reported under the zone name itself. The specified shared memory zone will collect the following statistics: | `ssl` | Object; SSL statistics.
Present if `server` sets `listen ssl;` | |--------------|----------------------------------------------------------------------------------| | `handshaked` | Number; the total number of successful SSL handshakes | | `reuses` | Number; the total number of session reuses during SSL handshake | | `timedout` | Number; the total number of timed out SSL handshakes | | `failed` | Number; the total number of failed SSL handshakes | | `requests` | Object; requests statistics | | `total` | Number; the total number of client requests | | `processing` | Number; the number of currently being processed client requests | | `discarded` | Number; the total number of client requests completed without sending a response | | `responses` | Object; responses statistics | | `

`     | Number; a non-zero number of responses with status  (100-599)              |
| `xxx`        | Number; a non-zero number of responses with other status codes                   |
| `data`       | Object; data statistics                                                          |
| `received`   | Number; the total number of bytes received from clients                          |
| `sent`       | Number; the total number of bytes sent to clients                                |

#### NOTE
The `responses` counters track only real responses that were actually
sent to the client. A request whose processing finished without sending a
response is counted in `discarded` and does not increment the
`responses` counters. In particular, `499` is not a response but
an internal service code, recorded only in the access log, that marks a
request whose processing ended without a response being sent; such requests
are reflected in `discarded`, never in `responses`.

Example:

```json
{
    "ssl":{
        "handshaked":4174,
        "reuses":0,
        "timedout":0,
        "failed":0
    },

    "requests":{
        "total":4327,
        "processing":0,
        "discarded":0
    },

    "responses":{
        "200":4305,
        "302":6,
        "304":12,
        "404":4
    },

    "data":{
        "received":733955,
        "sent":59207757
    }
}
```



#### `/status/http/location_zones/`

To collect the `location` metrics, set the [status_zone](https://en.angie.software//angie/docs/configuration/modules/http/index.md#status-zone) directive
in the context of [location](https://en.angie.software//angie/docs/configuration/modules/http/index.md#location) or [if in location](https://en.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#if):

```nginx
location / {
    root /usr/share/angie/html;
    status_zone location_zone;

    if ($request_uri ~* "^/condition") {
        # ...
        status_zone if_location_zone;
    }
}
```

To group the metrics by a custom value, use the alternative syntax.
Here, the metrics are aggregated by [$host](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-host),
with each group reported as a standalone zone:

```nginx
status_zone $host zone=server_zone:5;
```

The specified shared memory zone will collect the following statistics:

| `requests`   | Object; requests statistics                                                      |
|--------------|----------------------------------------------------------------------------------|
| `total`      | Number; the total number of client requests                                      |
| `discarded`  | Number; the total number of client requests completed without sending a response |
| `responses`  | Object; responses statistics                                                     |
| ``     | Number; a non-zero number of responses with status  (100-599)              |
| `xxx`        | Number; a non-zero number of responses with other status codes                   |
| `data`       | Object; data statistics                                                          |
| `received`   | Number; the total number of bytes received from clients                          |
| `sent`       | Number; the total number of bytes sent to clients                                |

#### NOTE
The `responses` counters track only real responses that were actually
sent to the client. A request whose processing finished without sending a
response is counted in `discarded` and does not increment the
`responses` counters. In particular, `499` is not a response but
an internal service code, recorded only in the access log, that marks a
request whose processing ended without a response being sent; such requests
are reflected in `discarded`, never in `responses`.

Example:

```json
{
  "requests": {
    "total": 4158,
    "discarded": 0
  },

  "responses": {
    "200": 4157,
    "304": 1
  },

  "data": {
    "received": 538200,
    "sent": 177606236
  }
}
```



#### `/status/http/metric_zones/`

Custom metrics defined by [metric_zone](https://en.angie.software//angie/docs/configuration/modules/http/http_metric.md#metric-zone) or [metric_complex_zone](https://en.angie.software//angie/docs/configuration/modules/http/http_metric.md#metric-complex-zone)
in the `http` context. Metrics are updated with the [metric](https://en.angie.software//angie/docs/configuration/modules/http/http_metric.md#id1)
directive or the module variables.

| `discarded`   | Number; the number of metric entries discarded because the zone ran out
of memory.                                                                                                           |
|---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `metrics`     | Object; metrics per key. For single-metric zones, values are numbers.
For complex zones, values are objects with metric names. For histogram
mode, values are objects with bucket names. |

If `discard_key` is set and some entries have been expired,
their aggregated metrics are exposed under this key.

Example:

```json
{
    "discarded": 3,
    "metrics": {
        "example.com": {
            "count": 42,
            "max": 8
        }
        "expired": {
            "count": 10,
            "max": 3.2
        }
    }
}
```



### Stream server



#### `/status/stream/server_zones/`

To collect the `server` metrics,
set the [status_zone](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#s-status-zone) directive in the [server](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#s-server) context:

```nginx
server {
    ...
    status_zone server_zone;
}
```

To group the metrics by a custom value, use the alternative syntax.
Here, the metrics are aggregated by [$server_addr](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#v-s-server-addr),
with each group reported as a standalone zone:

```nginx
status_zone $server_addr zone=server_zone:5;
```

The specified shared memory zone will collect the following statistics:

| `ssl`                 | Object; SSL statistics.
Present if `server` sets `listen ssl;`                                                                                  |
|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|
| `handshaked`          | Number; the total number of successful SSL handshakes                                                                                               |
| `reuses`              | Number; the total number of session reuses during SSL handshake                                                                                     |
| `timedout`            | Number; the total number of timed out SSL handshakes                                                                                                |
| `failed`              | Number; the total number of failed SSL handshakes                                                                                                   |
| `connections`         | Object; connections statistics                                                                                                                      |
| `total`               | Number; the total number of client connections                                                                                                      |
| `processing`          | Number; the number of currently being processed client connections                                                                                  |
| `discarded`           | Number; the total number of client connections
completed without creating a session                                                             |
| `passed`              | Number; the total number of client connections
relayed to another listening port with `pass` directives                                         |
| `sessions`            | Object; sessions statistics                                                                                                                         |
| `success`             | Number; the number of sessions completed with code 200, which means successful completion                                                           |
| `invalid`             | Number; the number of sessions completed with code 400, which happens when client data could not be parsed, e.g. the PROXY protocol header          |
| `forbidden`           | Number; the number of sessions completed with code 403, when access was forbidden, for example, when access is limited for certain client addresses |
| `internal_error`      | Number; the number of sessions completed with code 500, the internal server error                                                                   |
| `bad_gateway`         | Number; the number of sessions completed with code 502, bad gateway, for example, if an upstream server could not be selected or reached            |
| `service_unavailable` | Number; the number of sessions completed with code 503, service unavailable, for example, when access is limited by the number of connections       |
| `data`                | Object; data statistics                                                                                                                             |
| `received`            | Number; the total number of bytes received from clients                                                                                             |
| `sent`                | Number; the total number of bytes sent to clients                                                                                                   |

Example:

```json
{
  "ssl": {
    "handshaked": 24,
    "reuses": 0,
    "timedout": 0,
    "failed": 0
  },

  "connections": {
    "total": 24,
    "processing": 1,
    "discarded": 0,
    "passed": 2
  },

  "sessions": {
    "success": 24,
    "invalid": 0,
    "forbidden": 0,
    "internal_error": 0,
    "bad_gateway": 0,
    "service_unavailable": 0
  },

  "data": {
    "received": 2762947,
    "sent": 53495723
  }
}
```



#### `/status/stream/metric_zones/`

Custom metrics defined by [metric_zone](https://en.angie.software//angie/docs/configuration/modules/stream/stream_metric.md#s-metric-zone) or
[metric_complex_zone](https://en.angie.software//angie/docs/configuration/modules/stream/stream_metric.md#s-metric-complex-zone) in the `stream`
context. Metrics are updated with the [metric](https://en.angie.software//angie/docs/configuration/modules/stream/stream_metric.md#s-metric) directive or
the module variables.

| `discarded`   | Number; the number of metric entries discarded because the zone ran out
of memory.                                                                                                           |
|---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `metrics`     | Object; metrics per key. For single-metric zones, values are numbers.
For complex zones, values are objects with metric names. For histogram
mode, values are objects with bucket names. |

If `discard_key` is set and some entries have been expired,
their aggregated metrics are exposed under this key.

Example:

```json
{
    "discarded": 3,
    "metrics": {
        "127.0.0.1": {
            "count": 42,
            "max": 8
        },
        "expired": {
            "count": 10,
            "max": 3.2
        }
    }
}
```



### HTTP caches

```nginx
proxy_cache cache_zone;
proxy_cache_valid 200 10m;
```



#### `/status/http/caches/`

For each zone configured with [proxy_cache](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache), the following data is
stored:

```json
{
  "name_zone": {
    "size": 0,
    "cold": false,
    "hit": {
      "responses": 0,
      "bytes": 0
    },

    "stale": {
      "responses": 0,
      "bytes": 0
    },

    "updating": {
      "responses": 0,
      "bytes": 0
    },

    "revalidated": {
      "responses": 0,
      "bytes": 0
    },

    "miss": {
      "responses": 0,
      "bytes": 0,
      "responses_written": 0,
      "bytes_written": 0
    },

    "expired": {
      "responses": 0,
      "bytes": 0,
      "responses_written": 0,
      "bytes_written": 0
    },

    "bypass": {
      "responses": 0,
      "bytes": 0,
      "responses_written": 0,
      "bytes_written": 0
    }
  }
}
```

| `size`              | Number; the space the cache currently occupies on disk, in bytes.
Each cached entry is counted as the whole filesystem blocks its file
occupies, so this value always exceeds the total size of the cached
response bodies   |
|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `max_size`          | Number; the configured limit on the cache size, in bytes;
omitted if no limit is set                                                                                                                                                 |
| `cold`              | Boolean; `true` while the cache loader loads data from disk                                                                                                                                                                              |
| `hit`               | Object; statistics of valid cached responses ([proxy_cache_valid](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-valid))                                                                     |
| `responses`         | Number; the total number of responses read from the cache                                                                                                                                                                                |
| `bytes`             | Number; the total number of bytes read from the cache                                                                                                                                                                                    |
| `stale`             | Object; statistics of stale responses taken from the cache ([proxy_cache_use_stale](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-use-stale))                                               |
| `responses`         | Number; the total number of responses read from the cache                                                                                                                                                                                |
| `bytes`             | Number; the total number of bytes read from the cache                                                                                                                                                                                    |
| `updating`          | Object; statistics of stale responses taken from the cache while responses were being updated ([proxy_cache_use_stale](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-use-stale) updating)   |
| `responses`         | Number; the total number of responses read from the cache                                                                                                                                                                                |
| `bytes`             | Number; the total number of bytes read from the cache                                                                                                                                                                                    |
| `revalidated`       | Object; statistics of expired and revalidated responses taken from the cache ([proxy_cache_revalidate](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-revalidate))                           |
| `responses`         | Number; the total number of responses read from the cache                                                                                                                                                                                |
| `bytes`             | Number; the total number of bytes read from the cache                                                                                                                                                                                    |
| `miss`              | Object; statistics of responses not found in the cache                                                                                                                                                                                   |
| `responses`         | Number; the total number of corresponding responses                                                                                                                                                                                      |
| `bytes`             | Number; the total number of bytes read from the proxied server                                                                                                                                                                           |
| `responses_written` | Number; the total number of responses written to the cache                                                                                                                                                                               |
| `bytes_written`     | Number; the total number of bytes written to the cache                                                                                                                                                                                   |
| `expired`           | Object; statistics of expired responses not taken from the cache                                                                                                                                                                         |
| `responses`         | Number; the total number of corresponding responses                                                                                                                                                                                      |
| `bytes`             | Number; the total number of bytes read from the proxied server                                                                                                                                                                           |
| `responses_written` | Number; the total number of responses written to the cache                                                                                                                                                                               |
| `bytes_written`     | Number; the total number of bytes written to the cache                                                                                                                                                                                   |
| `bypass`            | Object; statistics of responses not looked up in the cache ([proxy_cache_bypass](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-bypass))                                                     |
| `responses`         | Number; the total number of corresponding responses                                                                                                                                                                                      |
| `bytes`             | Number; the total number of bytes read from the proxied server                                                                                                                                                                           |
| `responses_written` | Number; the total number of responses written to the cache                                                                                                                                                                               |
| `bytes_written`     | Number; the total number of bytes written to the cache                                                                                                                                                                                   |

In Angie PRO, if cache sharding is enabled with [proxy_cache_path](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-path) directives,
individual shards are exposed as object members of a `shards` object;
`size`, `max_size`, and `cold` are then reported for each
shard separately and are absent at the zone level:

| `shards`   | Object; lists individual shards as members                                                                                                              |
|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
| ``  | Object; represents an individual shard with its cache path for name                                                                                     |
| `size`     | Number; the space the shard currently occupies on disk, in bytes;
each cached entry is counted as the whole filesystem blocks its file
occupies |
| `max_size` | Number; the configured limit on the shard size, in bytes;
omitted if no limit is set                                                                |
| `cold`     | Boolean; `true` while the cache loader loads data from disk                                                                                             |
```json
{
  "name_zone": {
    "shards": {
        "/path/to/shard1": {
            "size": 0,
            "cold": false
        },

        "/path/to/shard2": {
            "size": 0,
            "cold": false
        }
    }
}
```



### ACME clients



#### `/status/http/acme_clients/`

For each configured [acme_client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) in the `http` block, returns the
current client and certificate status:

```json
{
  "state": "ready",
  "certificate": "valid",
  "details": "The client is ready to request a certificate.",
  "next_run": "2026-07-17T16:15:43.805Z"
}
```

| `state`       | String; ACME client state. Possible values: `ready`,
`requesting`, `disabled`, `failed`.                                       |
|---------------|------------------------------------------------------------------------------------------------------------------------------------|
| `certificate` | String; certificate status. Possible values: `valid`,
`expired`, `missing`, `mismatch`, `error`.                               |
| `details`     | String; short status details from the last ACME operation.                                                                         |
| `next_run`    | Date; next scheduled attempt to request or renew the certificate.
Not returned when `state` is `disabled` or
`requesting`. |



### limit_conn

```nginx
limit_conn_zone $binary_remote_addr zone=limit_conn_zone:10m;
```



#### `/status/http/limit_conns/`, `/status/stream/limit_conns/`

Objects for each configured [limit_conn in http](#limit-conn) or [limit_conn in stream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_limit_conn.md#s-limit-conn) contexts with the following fields:

```json
{
  "passed": 73,
  "skipped": 0,
  "rejected": 0,
  "exhausted": 0
}
```

| `passed`    | Number; the total number of passed connections                                                  |
|-------------|-------------------------------------------------------------------------------------------------|
| `skipped`   | Number; the total number of connections passed with zero-length key, or key exceeding 255 bytes |
| `rejected`  | Number; the total number of connections exceeding the configured limit                          |
| `exhausted` | Number; the total number of connections rejected due to exhaustion of zone storage              |



### limit_req

```nginx
limit_req_zone $binary_remote_addr zone=limit_req_zone:10m rate=1r/s;
```



#### `/status/http/limit_reqs/`

Objects for each configured [limit_req](#limit-req) with the following fields:

```json
{
  "passed": 54816,
  "skipped": 0,
  "delayed": 65,
  "rejected": 26,
  "exhausted": 0
}
```

| `passed`    | Number; the total number of passed requests                                                  |
|-------------|----------------------------------------------------------------------------------------------|
| `skipped`   | Number; the total number of requests passed with zero-length key, or key exceeding 255 bytes |
| `delayed`   | Number; the total number of delayed requests                                                 |
| `rejected`  | Number; the total number of rejected requests                                                |
| `exhausted` | Number; the total number of requests rejected due to exhaustion of zone storage              |



### HTTP upstream

To enable collection of the following metrics,
set the [zone](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone) directive in the [upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) context,
for instance:

```nginx
upstream upstream {
    zone upstream 256k;
    server backend.example.com service=_example._tcp resolve max_conns=5;
    keepalive 4;
}
```

The memory usage of this shared memory zone is reported by the
[/status/slabs/](#samp-status-slabs-zone) API section, keyed by the
zone's name.



#### `/status/http/upstreams/`

where  is the name of any [upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) specified with the [zone](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone) directive

```json
{
    "peers": {
        "192.168.16.4:80": {
            "server": "backend.example.com",
            "service": "_example._tcp",
            "backup": false,
            "weight": 5,
            "state": "up",
            "selected": {
                "current": 2,
                "total": 232
            },

            "max_conns": 5,
            "responses": {
                "200": 222,
                "302": 12
            },

            "data": {
                "sent": 543866,
                "received": 27349934
            },

            "health": {
                "fails": 0,
                "unavailable": 0,
                "downtime": 0,
                "header_time": 21,
                "response_time": 42
            },

            "sid": ""
        }
    },

    "keepalive": 2
}
```

| `peers`              | Object; contains the metrics of the upstream's peers as subobjects
whose names are canonical representations of the peers' addresses.
Members of each subobject:                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `server`             | String; the parameter of the [server](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) directive                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `service`            | String; name of service as it's specified in [server](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) directive, if configured                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `backup`             | Boolean; `true` for backup servers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `weight`             | Number; configured [weight](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `state`              | String; the current state of the peer and what requests are sent to it:

- `busy`: indicates that the number of requests to the server
  has reached the limit set by [max_conns](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server),
  and no new requests are sent to it;
- `down`: manually disabled, no requests are sent;
- `draining`: similar to `down`,
  but requests from previously bound sessions
  (via [sticky](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky)) are still sent;
- `recovering`: recovering after a failure
  according to [slow_start](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#slow-start),
  more and more requests are sent over time;
- `unavailable`: reached the [max_fails](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) limit,
  only trial client requests are sent
  at intervals defined by [fail_timeout](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#fail-timeout);
- `up`: operational, requests are sent as usual;

Additional states in Angie PRO:

- `checking`: configured as `essential` and being checked,
  only [probe requests](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe) are sent;
- `unhealthy`: non-operational,
  only [probe requests](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe) are sent. |
| `selected`           | Object; peer selection statistics                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `current`            | Number; the current number of connections to the peer                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `total`              | Number; total number of requests forwarded to the peer                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `last`               | String or number; time when the peer was last selected,
formatted as a [date](#api-date-format)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `max_conns`          | Number; the configured [maximum](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) number of simultaneous active connections to the peer, if specified                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `responses`          | Object; response statistics                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ``             | Number; a non-zero number of responses with status  (100-599)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `xxx`                | Number; a non-zero number of responses with other status codes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `data`               | Object; data statistics                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `received`           | Number; the total number of bytes received from the peer                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `sent`               | Number; the total number of bytes sent to the peer                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `health`             | Object; health statistics                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `fails`              | Number; the total number of unsuccessful attempts to communicate with the peer                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `unavailable`        | Number; how many times the peer became `unavailable` due to reaching the [max_fails](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) limit                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `downtime`           | Number; the total time (in milliseconds) when the peer was `unavailable` for selection                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `downstart`          | String or number; time when the peer became `unavailable`,
formatted as a [date](#api-date-format).
This field is present only while the peer is in the `unavailable`
state; otherwise it is absent                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `header_time`        | Number; average time (in milliseconds)
to receive the response headers from the server;
see [response_time_factor](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-response-time-factor)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `response_time`      | Number; average time (in milliseconds)
to receive the entire response from the server;
see [response_time_factor](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-response-time-factor)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `sid`                | String; [configured id](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve) of the server in the upstream group                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `feedback`
(PRO) | Number; the current average feedback value used
by the [feedback](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-feedback) load balancing method,
present only when this method is used                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `keepalive`          | Number; the current number of cached connections                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `backup_switch`      | Object; contains the current state of the active backup logic,
present if [backup_switch (PRO)](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-backup-switch) is configured for the upstream                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `active`             | Number; the level of the active group
that is currently used for load balancing requests.
If the active group is the primary one, the value is 0                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `timeout`            | Number; remaining wait time in milliseconds,
after which the balancer will re-check for healthy nodes
in groups with lower levels, starting from the primary group,
while groups with higher levels are not checked;
not displayed for the primary group (level 0)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |



##### `health/probes` (PRO)

If the upstream has [upstream_probe (PRO)](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe) probes configured,
the `health` object also has a `probes` subobject
that stores the server's health probe counters,
while `state`, apart from the values listed in the table above,
can also be `checking` and `unhealthy`:

```json
{
    "192.168.16.4:80": {
        "state": "unhealthy",
        "...": "...",
        "health": {
            "...": "...",
            "probes": {
                "count": 10,
                "fails": 10,
                "last": "2026-07-17T09:56:07Z"
            }
        }
    }
}
```

The `checking` value of `state` isn't counted as `downtime`
and means that the server, which has a probe configured as `essential`,
hasn't been checked yet;
the `unhealthy` value means that the server is malfunctioning.
Both states also imply that the server isn't included in load balancing.
For details of health probes, see [upstream_probe](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe).

Counters in `probes`:

| `count`   | Number; total probes for this server                                           |
|-----------|--------------------------------------------------------------------------------|
| `fails`   | Number; total failed probes                                                    |
| `last`    | String or number; last probe time,
formatted as a [date](#api-date-format) |



##### `queue` (PRO)

If a [request queue](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-queue) is configured for the upstream,
the upstream object also contains a nested `queue` object
with request queue counters:

```json
{
    "queue": {
        "queued": 20112,
        "waiting": 1011,
        "dropped": 6031,
        "timedout": 560,
        "overflows": 13
    }
}
```

Counter values are summed across all worker processes:

| `queued`    | Number; total number of requests that entered the queue                                                          |
|-------------|------------------------------------------------------------------------------------------------------------------|
| `waiting`   | Number; current number of requests in the queue                                                                  |
| `dropped`   | Number; total number of requests removed from the queue
because the client prematurely closed the connection |
| `timedout`  | Number; total number of requests removed from the queue due to timeout                                           |
| `overflows` | Number; total number of queue overflow occurrences                                                               |



### Stream upstream

To enable collection of the following metrics,
set the [zone](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-zone) directive in the [upstream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-upstream) context,
for instance:

```nginx
upstream upstream {
    zone upstream 256k;
    server backend.example.com service=_example._tcp resolve max_conns=5;
    keepalive 4;
}
```

The memory usage of this shared memory zone is reported by the
[/status/slabs/](#samp-status-slabs-zone) API section, keyed by the
zone's name.



#### `/status/stream/upstreams/`

Here,  is the name of an [upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) that is
configured with a [zone](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone) directive.

```json
{
    "peers": {
        "192.168.16.4:1935": {
            "server": "backend.example.com",
            "service": "_example._tcp",
            "backup": false,
            "weight": 5,
            "state": "up",
            "selected": {
                "current": 2,
                "total": 232
            },

            "max_conns": 5,
            "data": {
                "sent": 543866,
                "received": 27349934
            },

            "health": {
                "fails": 0,
                "unavailable": 0,
                "downtime": 0,
                "connect_time": 3,
                "first_byte_time": 21,
                "last_byte_time": 42
            }
        }
    }
}
```

| `peers`                           | Object; contains the metrics of the upstream's peers as subobjects
whose names are canonical representations of the peers' addresses.
Members of each subobject:                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
|-----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `server`                          | String; address set by the [server](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server) directive                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `service`                         | String; service name, if set by the [server](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server) directive                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `backup`                          | Boolean; `true` for backup servers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `weight`                          | Number; the [weight](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server) set for the peer                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `state`                           | String; the current state of the peer and what requests are sent to it:

- `busy`: indicates that the number of requests to the server
  has reached the limit set by [max_conns](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server),
  and no new requests are sent to it
- `down`: manually disabled, no requests are sent
- `draining`: similar to `down`,
  but requests from previously bound sessions
  (via [sticky](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-sticky)) are still sent
- `recovering`: recovering after a failure
  according to [slow_start](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-slow-start),
  more and more requests are sent over time
- `unavailable`: reached the [max_fails](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-max-fails) limit,
  only trial client requests are sent
  at intervals defined by [fail_timeout](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-fail-timeout)
- `up`: operational, requests are sent as usual

Additional states in Angie PRO:

- `checking`: configured as `essential` and being checked,
  only [probe requests](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe) are sent
- `unhealthy`: non-operational,
  only [probe requests](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe) are sent |
| `selected`                        | Object; statistics on selecting this peer for connections                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `current`                         | Number; current number of connections to the peer                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `total`                           | Number; total number of connections forwarded to the peer                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `last`                            | String or number; time when the peer was last selected,
formatted as a [date](#api-date-format)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `max_conns`                       | Number;
[maximum](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server)
number of simultaneous active connections to the peer, if set                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `data`                            | Object; data transfer statistics                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `received`                        | Number; total bytes received from the peer                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `sent`                            | Number; total bytes sent to the peer                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `health`                          | Object; peer health statistics                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `fails`                           | Number; total failed attempts to reach the peer                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `unavailable`                     | Number; total number of times the peer became `unavailable` due to
reaching the [max_fails](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-max-fails) value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `downtime`                        | Number; total time (in milliseconds) that the peer was
`unavailable` (unavailable for selection)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `downstart`                       | String or number; time when the peer last became `unavailable`,
formatted as a [date](#api-date-format).
This field is present only while the peer is in the `unavailable`
state; otherwise it is absent                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `connect_time`                    | Number; average time (in milliseconds)
to establish a connection with the server;
see the [response_time_factor](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-response-time-factor) directive                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `first_byte_time`                 | Number; average time (in milliseconds)
to receive the first byte of the response from the server;
see the [response_time_factor](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-response-time-factor) directive                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `last_byte_time`                  | Number; average time (in milliseconds)
to receive the complete response from the server;
see the [response_time_factor](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-response-time-factor) directive                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `feedback`
(PRO)              | Number; the current average feedback value used
by the [feedback](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-feedback) load balancing method,
present only when this method is used                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `backup_switch`
(PRO 1.10.0+) | Object; contains the current state of active backup logic,
present if [backup_switch (PRO)](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-backup-switch) is configured for the upstream                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `active`                          | Number; level of the active group
currently used for load balancing.
If the active group is the primary group, the value is 0                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `timeout`                         | Number; remaining wait time in milliseconds
after which the load balancer will recheck for healthy nodes
in groups with lower levels, starting from the primary group,
while groups with higher levels are not checked;
not displayed for the primary group (level 0)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |

In Angie PRO, if the upstream has [upstream_probe (PRO)](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe) probes configured,
the `health` object also has a `probes` subobject
that stores the server's health probe counters,
while `state`, in addition to the values from the table above,
can also be `checking` and `unhealthy`:

```json
{
    "192.168.16.4:80": {
        "state": "unhealthy",
        "...": "...",
        "health": {
            "...": "...",
            "probes": {
                "count": 2,
                "fails": 2,
                "last": "2026-07-17T11:03:54Z"
            }
        }
    }
}
```

The `checking` value of `state` means that the server,
which has a probe configured with the `essential` parameter,
hasn't been checked yet;
the `unhealthy` value means that the server is non-operational.
Both states also mean that the server isn't included in load balancing.
For details of health probes, see [upstream_probe](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe).

Counters in `probes`:

| `count`   | Number; total number of probes for this server                                        |
|-----------|---------------------------------------------------------------------------------------|
| `fails`   | Number; number of failed probes                                                       |
| `last`    | String or number; time of the last probe,
formatted as a [date](#api-date-format) |





## Certificates



### `/certificates/`

A top-level object of the API, separate from the [/status/](#metrics)
statistics tree, that reports the TLS certificates Angie has loaded.

A certificate isn't listed under `static` if its certificate or key file
name contains a variable — including one supplied by an ACME client through
the [$acme_cert_](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-cert-name) variable. A certificate
shared by several servers is listed once.

The following example loads a static certificate and obtains another
certificate with an ACME client. The ACME client requires a configured
[resolver](https://en.angie.software//angie/docs/configuration/modules/http/index.md#resolver) to resolve the directory hostname:

```nginx
http {
    resolver 127.0.0.53;

    acme_client example https://acme.example.com/directory;

    server {
        listen      443 ssl;
        server_name www.example.com;

        ssl_certificate     example.com.crt;
        ssl_certificate_key example.com.key;

        location /certificates/ {
            api /certificates/;
        }
    }

    server {
        listen      443 ssl;
        server_name acme.example.com;

        acme                example;
        ssl_certificate     $acme_cert_example;
        ssl_certificate_key $acme_cert_key_example;
    }
}
```

In response to the request
`curl https://www.example.com/certificates/`, Angie returns:

```json
{
    "static": {
        "example.com.crt": {
            "key": "RSA (2048 bits)",
            "chain": [
                {
                    "subject": {
                        "common_name": "example.com",
                        "alt_names": [
                            "example.com",
                            "www.example.com"
                        ],
                        "organization": "Example, Inc."
                    },

                    "issuer": {
                        "common_name": "Example Root CA",
                        "country": "US",
                        "organization": "Example, Inc."
                    },

                    "validity": {
                        "since": "Sep 18 19:46:19 2022 GMT",
                        "until": "Jun 15 19:46:19 2025 GMT"
                    }
                }
            ]
        }
    },

    "acme_clients": {
        "example": {
            "key": "EC (prime256v1)",
            "chain": [
                {
                    "subject": {
                        "common_name": "acme.example.com"
                    },

                    "issuer": {
                        "common_name": "Example ACME CA"
                    },

                    "validity": {
                        "since": "Sep 18 19:46:19 2022 GMT",
                        "until": "Dec 17 19:46:19 2022 GMT"
                    }
                }
            ]
        }
    }
}
```

| `static`       | Object; server certificates set with [ssl_certificate](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-certificate) in HTTP,
[ssl_certificate](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#s-ssl-certificate) in Stream, or [ssl_certificate](https://en.angie.software//angie/docs/configuration/modules/mail/mail_ssl.md#m-ssl-certificate) in
Mail, each keyed by the certificate file name. In builds with
`--with-ntls`, it also includes certificates set with
[proxy_ssl_certificate](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ssl-certificate) in HTTP or [proxy_ssl_certificate](https://en.angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-ssl-certificate)
in Stream for authenticating to proxied servers   |
|----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `acme_clients` | Object; available when Angie is built with the HTTP [ACME](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme) module, which is also required by the Stream [ACME](https://en.angie.software//angie/docs/configuration/modules/stream/stream_acme.md#stream-acme) module. Contains certificates obtained by
[ACME clients](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) for HTTP and Stream servers. Each
entry is keyed by the [acme_client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) name. Only clients that have
already obtained a certificate are listed                                                                                                                                                                                |

Each entry of `static` and `acme_clients` describes a single
certificate bundle:

| `key`               | String; private key type and size (or curve), for example
`RSA (2048 bits)`, `EC (prime256v1)`, or
`DH (2048 bits)`                                                                                  |
|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `chain`             | Array; the certificates of the bundle, starting with the leaf (server)
certificate followed by any intermediate certificates, toward the root.
Each element is an object describing one certificate: |
| `subject`           | Object; the subject distinguished name                                                                                                                                                                       |
| `common_name`       | String; Common Name (`CN`)                                                                                                                                                                                   |
| `alt_names`         | Array of strings; the DNS names and IP addresses from the Subject
Alternative Name extension                                                                                                             |
| `country`           | String; Country (`C`)                                                                                                                                                                                        |
| `state_or_province` | String; State or Province Name (`ST`)                                                                                                                                                                        |
| `organization`      | String; Organization (`O`)                                                                                                                                                                                   |
| `issuer`            | Object; the issuer distinguished name, with the same fields as
`subject`                                                                                                                                 |
| `validity`          | Object; the certificate validity period                                                                                                                                                                      |
| `since`             | String; start of the validity period (`notBefore`)                                                                                                                                                           |
| `until`             | String; end of the validity period (`notAfter`)                                                                                                                                                              |

The fields of `subject` and `issuer` appear only when present in the
certificate.



## Dynamic Configuration API (PRO)

The API includes a `/config` section that enables dynamic updates
to Angie's configuration in JSON format
with `PUT`, `PATCH`, and `DELETE` HTTP requests.
All updates are atomic: new settings are applied as a whole,
or none are applied at all.
On error, Angie reports the reason.



### Subsections of `/config`

Currently, configuration of individual servers within upstreams is available
in the `/config` section for the [HTTP](#api-config-http-upstreams-servers) and [stream](#api-config-stream-upstreams-servers) modules; the number of settings
eligible for dynamic configuration is steadily increasing.



#### `/config/http/upstreams//servers/`

Enables configuring individual upstream peers,
including deleting existing peers or adding new ones.

URI path parameters:

| ``   | Name of the upstream; to be configurable via `/config`, it must
have a [zone](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone) directive configured, defining a shared
memory zone.                                                                        |
|----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ``       | The peer's name within the upstream, defined as
`@`, where:

- `@` is an optional service name, used for
  SRV record resolution.
- `` is the domain name of the service (if `resolve`
  is present) or its IP; an optional port can be defined here. |

For example, the following configuration:

```nginx
upstream backend {
    server backend.example.com service=_http._tcp resolve;
    server 127.0.0.1;
    zone backend 1m;
}
```

Allows the following peer names:

```console
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/_http._tcp@backend.example.com/
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/127.0.0.1:80/
```

This API subsection enables setting the `weight`, `max_conns`,
`max_fails`, `fail_timeout`, `slow_start`, `backup`, `down` and
`sid` parameters, as described in [server](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server).

#### NOTE
There is no separate `drain` parameter here;
to enable `drain`,
set `down` to the string value `drain`:

```console
$ curl -X PUT -d \"drain\" \
  http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/down
```

Example:

```console
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com?defaults=on
```

```json
{
    "weight": 1,
    "max_conns": 0,
    "max_fails": 1,
    "fail_timeout": 10,
    "slow_start": 0,
    "backup": true,
    "down": false,
    "sid": ""
}
```

Actually available parameters are limited to the ones supported by the
current load balancing method of the [upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream).
So, if the upstream is configured with the `random` method:

```nginx
upstream backend {
    zone backend 256k;
    server backend.example.com resolve max_conns=5;
    random;
}
```

You will be unable to add a new peer that defines `backup`:

```console
$ curl -X PUT -d '{ "backup": true }' \
    http://127.0.0.1/config/http/upstreams/backend/servers/backend1.example.com
```

```json
{
    "error": "FormatError",
    "description": "The \"backup\" field is unknown."
}
```



#### `/config/stream/upstreams//servers/`

Enables configuring individual upstream peers,
including deleting existing peers or adding new ones.

URI path parameters:

| ``   | Name of the `upstream` block;
to be configurable via `/config`,
it must have a [zone](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-zone) directive configured,
defining a shared memory zone.                                                      |
|----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ``       | The peer's name within the upstream, defined as
`@`, where:

- `@` is an optional service name, used for
  SRV record resolution.
- `` is the domain name of the service (if `resolve`
  is present) or its IP; an optional port can be defined here. |

For example, the following configuration:

```nginx
upstream backend {
    server backend.example.com:8080 service=_example._tcp resolve;
    server 127.0.0.1:12345;
    zone backend 1m;
}
```

Allows the following peer names:

```console
$ curl http://127.0.0.1/config/stream/upstreams/backend/servers/_example._tcp@backend.example.com:8080/
$ curl http://127.0.0.1/config/stream/upstreams/backend/servers/127.0.0.1:12345/
```

This API subsection enables setting the `weight`,
`max_conns`, `max_fails`, `fail_timeout`, `slow_start`, `backup`, and
`down` parameters, as described in [server](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server).

#### NOTE
There is no separate `drain` parameter here;
to enable `drain` mode,
set `down` to the string value `drain`:

```console
$ curl -X PUT -d \"drain\" \
  http://127.0.0.1/config/stream/upstreams/backend/servers/backend.example.com/down
```

Example:

```console
$ curl http://127.0.0.1/config/stream/upstreams/backend/servers/backend.example.com?defaults=on
```

```json
{
    "weight": 1,
    "max_conns": 0,
    "max_fails": 1,
    "fail_timeout": 10,
    "slow_start": 0,
    "backup": true,
    "down": false,
}
```

Actually available parameters are limited to the ones supported by the
current load balancing method of the [upstream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-upstream).
So, if the upstream is configured with the `random` method:

```nginx
upstream backend {
    zone backend 256k;
    server backend.example.com resolve max_conns=5;
    random;
}
```

You will be unable to add a new peer that defines `backup`:

```console
$ curl -X PUT -d '{ "backup": true }' \
    http://127.0.0.1/config/stream/upstreams/backend/servers/backend1.example.com
```

```json
{
    "error": "FormatError",
    "description": "The \"backup\" field is unknown."
}
```

When deleting peers, you can set the
`connection_drop=` argument (PRO) to override the
[proxy_connection_drop](https://en.angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-connection-drop) settings:

```console
$ curl -X DELETE \
    http://127.0.0.1/config/stream/upstreams/backend/servers/backend1.example.com?connection_drop=off

$ curl -X DELETE \
    http://127.0.0.1/config/stream/upstreams/backend/servers/backend2.example.com?connection_drop=on

$ curl -X DELETE \
    http://127.0.0.1/config/stream/upstreams/backend/servers/backend3.example.com?connection_drop=1000
```



### HTTP Methods

Let's consider the semantics of each HTTP method applicable to this section
using the following upstream configuration as an example:

```nginx
http {
    # ...

    upstream backend {
        zone upstream 256k;
        server backend.example.com resolve max_conns=5;
        # ...
    }

    server {
        # ...

        location /config/ {
            api /config/;

            allow 127.0.0.1;
            deny all;
        }
    }
}
```



#### GET

The `GET` HTTP method queries an entity at any existing path within
`/config`, just as it does for other API sections.

For example, the
`/config/http/upstreams/backend/servers/`
upstream server branch enables these queries:

```console
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/max_conns
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
$ curl http://127.0.0.1/config/http/upstreams/backend/servers
$ # ...
$ curl http://127.0.0.1/config
```

You can obtain default parameter values with the `defaults=on` query
argument; see [Query arguments](#api-query-arguments).



#### PUT

The `PUT` HTTP method creates a new JSON entity at the specified path
or *entirely* replaces an existing one.

For example, to add the `max_fails` parameter, not specified earlier,
to the `backend.example.com` server within the `backend` upstream:

```console
$ curl -X PUT -d '2' \
    http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/max_fails
```

```json
{
    "success": "Updated",
    "description": "Existing configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com/max_fails\" was updated with replacing."
}
```

Verify the changes:

```console
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
```

```json
{
    "max_conns": 5,
    "max_fails": 2
}
```



#### DELETE

The `DELETE` HTTP method deletes *previously defined* settings at the specified path;
in doing so, it restores the default values if there are any.

For example, to delete the previously modified `max_fails` parameter
of the `backend.example.com` server within the `backend` upstream:

```console
$ curl -X DELETE \
    http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/max_fails
```

```console
{
    "success": "Reset",
    "description": "Configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com/max_fails\" was reset to default."
}
```

Verify the changes using the `defaults=on` argument:

```console
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com?defaults=on
```

```json
{
    "weight": 1,
    "max_conns": 5,
    "max_fails": 1,
    "fail_timeout": 10,
    "slow_start": 0,
    "backup": false,
    "down": false,
    "sid": ""
}
```

The `max_fails` parameter has returned to its default value.

When deleting servers, you can set the `connection_drop=` argument
(PRO) to override the [proxy_connection_drop](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-connection-drop), [grpc_connection_drop](https://en.angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-connection-drop),
[fastcgi_connection_drop](https://en.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-connection-drop), [scgi_connection_drop](https://en.angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-connection-drop), and
[uwsgi_connection_drop](https://en.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-connection-drop) settings:

```console
$ curl -X DELETE \
    http://127.0.0.1/config/http/upstreams/backend/servers/backend1.example.com?connection_drop=off

$ curl -X DELETE \
    http://127.0.0.1/config/http/upstreams/backend/servers/backend2.example.com?connection_drop=on

$ curl -X DELETE \
    http://127.0.0.1/config/http/upstreams/backend/servers/backend3.example.com?connection_drop=1000
```



#### PATCH

The `PATCH` HTTP method creates a new entity at the specified path
or partially replaces or complements an existing one
([RFC 7386](https://datatracker.ietf.org/doc/html/rfc7396))
by supplying a JSON definition in its payload.

The method operates as follows: if the entities from the new definition
exist in the configuration, they are overwritten; otherwise, they are added.

For example, to change the `down` parameter of the
`backend.example.com` server within the `backend` upstream,
leaving the rest intact:

```console
$ curl -X PATCH -d '{ "down": true }' \
    http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
```

```json
{
    "success": "Updated",
    "description": "Existing configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com\" was updated with merging."
}
```

Verify the changes:

```console
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
```

```json
{
    "max_conns": 5,
    "down": true
}
```

Note that the JSON object supplied with the `PATCH` request *was merged* with the
existing one instead of replacing it entirely, as would be the case with `PUT`.

The `null` values are a special case; they are used to delete
specific configuration items during such a merge.

#### NOTE
This deletion is identical to `DELETE`;
in particular, it restores the default values.

For example, to delete the `down` parameter added earlier
and simultaneously update `max_conns`:

```console
$ curl -X PATCH -d '{ "down": null, "max_conns": 6 }' \
    http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
```

```json
{
    "success": "Updated",
    "description": "Existing configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com\" was updated with merging."
}
```

Verify the changes:

```console
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
```

```json
{
    "max_conns": 6
}
```

The `down` parameter, for which a `null` value was supplied, was deleted;
the `max_conns` value was updated.


# https://en.angie.software/angie/docs/configuration/modules/http/http_auth_basic.md





# Auth Basic

Allows limiting access to resources by validating the user name and password using the "HTTP Basic Authentication" protocol.

Access can also be limited by [address](https://en.angie.software//angie/docs/configuration/modules/http/http_access.md#http-access) or by the
[result of subrequest](https://en.angie.software//angie/docs/configuration/modules/http/http_auth_request.md#http-auth-request). Simultaneous limitation of
access by address and by password is controlled by the [satisfy](https://en.angie.software//angie/docs/configuration/modules/http/index.md#satisfy) directive.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by
default; it can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-http_auth_basic_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
location / {
    auth_basic           "closed site";
    auth_basic_user_file conf/htpasswd;
}
```



## Directives





### auth_basic

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `auth_basic` string | `off`;         |
|------------------------------------------------------------------------------------------|--------------------------------------|
| Default                                                                                  | `auth_basic off;`                    |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location, limit_except |

Enables validation of user name and password using the "HTTP Basic Authentication" protocol. The specified parameter is used as a realm. Parameter value can contain [variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables).

| `off`   | cancels the effect of the auth_basic directive inherited from the previous configuration level   |
|---------|--------------------------------------------------------------------------------------------------|





### auth_basic_user_file

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `auth_basic_user_file` file;         |
|------------------------------------------------------------------------------------------|--------------------------------------|
| Default                                                                                  | —                                    |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location, limit_except |

Specifies a file that keeps user names and passwords. The format is as follows:

```none
# comment
name1:password1
name2:password2:comment
name3:password3
```

The file name can contain variables.

The following password types are supported:

* encrypted with the crypt() function; can be generated using the `htpasswd` utility from the Apache HTTP Server distribution or the "openssl passwd" command;
* hashed with the Apache variant of the MD5-based password algorithm (apr1); can be generated with the same tools;
* specified by the "{scheme}data" syntax as described in [RFC 2307](https://datatracker.ietf.org/doc/html/rfc2307#section-5.3); currently implemented schemes include PLAIN (an example one, should not be used), SHA (plain SHA-1 hashing, should not be used) and SSHA (salted SHA-1 hashing, used by some software packages, notably OpenLDAP and Dovecot).

#### WARNING
Support for SHA scheme was added only to aid in migration from other web servers. It should not be used for new passwords, since unsalted SHA-1 hashing that it employs is vulnerable to [rainbow table](http://en.wikipedia.org/wiki/Rainbow_attack) attacks.


# https://en.angie.software/angie/docs/configuration/modules/http/http_auth_request.md





# Auth Request

Implements client authorization based on the result of a subrequest. If the subrequest returns a 2xx response code, the access is allowed. If it returns 401 or 403, the access is denied with the corresponding error code. Any other response code returned by the subrequest is considered an error.

For the 401 error, the client also receives the `WWW-Authenticate` header from the subrequest response.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module isn't built
by default; it must be enabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--with-http_auth_request_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.

The module may be combined with other access modules, such as
[Access](https://en.angie.software//angie/docs/configuration/modules/http/http_access.md#http-access) and [Auth Basic](https://en.angie.software//angie/docs/configuration/modules/http/http_auth_basic.md#http-auth-basic), via the [satisfy](https://en.angie.software//angie/docs/configuration/modules/http/index.md#satisfy)
directive.



## Configuration Example

```nginx
location /private/ {
    auth_request /auth;
#    ...
}

location = /auth {
    proxy_pass ...;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_set_header X-Original-URI $request_uri;
}
```



## Directives





### auth_request

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `auth_request` `uri` | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------|
| Default                                                                                  | `auth_request off;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location          |

Enables authorization based on the result of a subrequest and sets the URI to which the subrequest will be sent.





### auth_request_set

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `auth_request_set` $variable value;   |
|------------------------------------------------------------------------------------------|---------------------------------------|
| Default                                                                                  | —                                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                |

Sets the request variable to the given value after the authorization request completes. The value may contain [variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables) from the authorization request, such as `$upstream_http_*`.


# https://en.angie.software/angie/docs/configuration/modules/http/http_autoindex.md





# AutoIndex

Serves requests ending with a slash (`/`) and produces a directory listing. Usually, a request is passed to the `AutoIndex` module when the [Index](https://en.angie.software//angie/docs/configuration/modules/http/http_index.md#http-index) module cannot find an index file.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by
default; it can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-http_autoindex_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
location / {
    autoindex on;
}
```



## Directives





### autoindex

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `autoindex` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| Default                                                                                  | `autoindex off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location      |

Enables or disables the directory listing output.





### autoindex_exact_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `autoindex_exact_size` `on` | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------------------|
| Default                                                                                  | `autoindex_exact_size on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                 |

For the HTML [format](#autoindex-format), specifies whether exact file sizes should be output in the directory listing, or rather rounded to kilobytes, megabytes, and gigabytes.





### autoindex_format

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `autoindex_format` `html` | `xml` | `json` | `jsonp`;   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------|
| Default                                                                                  | `autoindex_format html;`                                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                  |

Sets the format of a directory listing.

When the JSONP format is used, the name of a callback function is set with the `callback` request argument. If the argument is missing or has an empty value, then the JSON format is used.

The XML output can be transformed using the [XSLT](https://en.angie.software//angie/docs/configuration/modules/http/http_xslt.md#http-xslt) module.

### Output Formats

Object fields in responses contain the following data:

| Field   | Description                                                                                                                       |
|---------|-----------------------------------------------------------------------------------------------------------------------------------|
| `name`  | File or directory name                                                                                                            |
| `type`  | Object type: `file` or `directory`                                                                                                |
| `size`  | File size in bytes; omitted for directories.
[autoindex_exact_size](#autoindex-exact-size) affects only the
`html` format |
| `mtime` | Last modification time in Unix time format                                                                                        |

HTML

```html


    Index of /files/


    Index of /files/
    
                ../
            example.txt               12-Jun-2025 14:21    1234
            image.png                   12-Jun-2025 14:21    4321
            
    


```

XML

```xml


    example.txt
    file
    1234
    2025-06-12T14:21:00Z


    image.png
    file
    4321
    2025-06-12T14:21:00Z


```

JSON

```json
[
{
    "name": "example.txt",
    "type": "file",
    "size": 1234,
    "mtime": "2025-06-12T14:21:00Z"
},
{
    "name": "image.png",
    "type": "file",
    "size": 4321,
    "mtime": "2025-06-12T14:21:00Z"
}
]
```

JSONP

```javascript
callback([
{
    "name": "example.txt",
    "type": "file",
    "size": 1234,
    "mtime": "2025-06-12T14:21:00Z"
},
{
    "name": "image.png",
    "type": "file",
    "size": 4321,
    "mtime": "2025-06-12T14:21:00Z"
}
]);
```





### autoindex_localtime

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `autoindex_localtime` `on` | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------------|
| Default                                                                                  | `autoindex_localtime off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                |

For the HTML [format](#autoindex-format), specifies whether times in the directory listing should be output in the local time zone or UTC.


# https://en.angie.software/angie/docs/configuration/modules/http/http_browser.md





# Browser

The module creates variables whose values depend on the value of the `User-Agent` request header field.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by
default; it can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-http_browser_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Variables



### `$ancient_browser`

equals the value set by the [ancient_browser_value](#ancient-browser-value) directive, if a browser was identified as ancient;



### `$modern_browser`

equals the value set by the [modern_browser_value](#modern-browser-value) directive, if a browser was identified as modern;



### `$msie`

equals "1" if a browser was identified as MSIE of any version.



## Configuration Example



### Choosing an index file:

```nginx
modern_browser_value "modern.";

modern_browser msie      5.5;
modern_browser gecko     1.0.0;
modern_browser opera     9.0;
modern_browser safari    413;
modern_browser konqueror 3.0;

index index.${modern_browser}html index.html;
```



### Redirection for old browsers:

```nginx
modern_browser msie      5.0;
modern_browser gecko     0.9.1;
modern_browser opera     8.0;
modern_browser safari    413;
modern_browser konqueror 3.0;

modern_browser unlisted;

ancient_browser Links Lynx netscape4;

if ($ancient_browser) {
    rewrite ^ /ancient.html;
}
```



## Directives





### ancient_browser

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ancient_browser` string ...;   |
|------------------------------------------------------------------------------------------|---------------------------------|
| Default                                                                                  | —                               |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location          |

If any of the specified substrings is found in the `User-Agent` request header field, the browser will be considered ancient. The special string "netscape4" corresponds to the regular expression "^Mozilla/[1-4]".





### ancient_browser_value

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ancient_browser_value` string;   |
|------------------------------------------------------------------------------------------|-----------------------------------|
| Default                                                                                  | `ancient_browser_value 1;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location            |

Sets a value for the [$ancient_browser](#v-ancient-browser) variable.





### modern_browser

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `modern_browser` browser version;

`modern_browser` `unlisted`;   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------|
| Default                                                                                  | —                                                                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                    |

Specifies a version starting from which a browser is considered modern. A
browser can be any one of the following: `msie`, `gecko` (browsers
based on Mozilla), `opera`, `safari`, or `konqueror`.

Versions can be specified in the following formats: X, X.X, X.X.X, or X.X.X.X. The maximum values for each of the formats are 4000, 4000.99, 4000.99.99, and 4000.99.99.99, respectively.

The special value `unlisted` specifies to consider a browser as modern if it was not listed by the modern_browser and [ancient_browser](#id4) directives. Otherwise such a browser is considered ancient. If a request does not provide the `User-Agent` field in the header, the browser is treated as not being listed.





### modern_browser_value

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `modern_browser_value` string;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | `modern_browser_value 1;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location           |

Sets a value for the [$modern_browser](#v-modern-browser) variable.


# https://en.angie.software/angie/docs/configuration/modules/http/http_charset.md





# Charset

The module adds the specified charset to the `Content-Type` response header field. In addition, the module can convert data from one charset to another, with some limitations:

* conversion is performed one way — from server to client,
* only single-byte charsets can be converted
* or single-byte charsets to/from UTF-8.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by
default; it can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-http_charset_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
include        conf/koi-win;

charset        windows-1251;
source_charset koi8-r;
```



## Directives





### charset

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `charset` charset | `off`;             |
|------------------------------------------------------------------------------------------|----------------------------------------|
| Default                                                                                  | `charset off;`                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location, if in location |

Adds the specified charset to the `Content-Type` response header field. If this charset is different from the charset specified in the [source_charset](#source-charset) directive, a conversion is performed.

The parameter `off` cancels the addition of charset to the `Content-Type` response header field.

A charset can be defined with a variable:

```nginx
charset $charset;
```

In such a case, all possible values of a variable need to be present in the
configuration at least once in the form of the [charset_map](#charset-map),
[charset](#id1), or [source_charset](#source-charset) directives. For `utf-8`,
`windows-1251`, and `koi8-r` charsets, it is sufficient to include
the files `conf/koi-win`, `conf/koi-utf`, and `conf/win-utf`
into configuration. For other charsets, simply making a fictitious conversion
table works, for example:

```nginx
charset_map iso-8859-5 _ { }
```

In addition, a charset can be set in the `X-Accel-Charset` response header field. This capability can be disabled using the [proxy_ignore_headers](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ignore-headers), [fastcgi_ignore_headers](https://en.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-ignore-headers), [uwsgi_ignore_headers](https://en.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-ignore-headers), [scgi_ignore_headers](https://en.angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-ignore-headers), and [grpc_ignore_headers](https://en.angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-ignore-headers) directives.





### charset_map

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `charset_map` charset1 charset2  { ... }   |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| Default                                                                                  | —                                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                                       |

Describes the conversion table from one charset to another. A reverse conversion table is built using the same data. Character codes are given in hexadecimal. Missing characters in the range 80-FF are replaced with "?". When converting from UTF-8, characters missing in a one-byte charset are replaced with "&#XXXX;".

Example:

```nginx
charset_map koi8-r windows-1251 {
    C0 FE ; # small yu
    C1 E0 ; # small a
    C2 E1 ; # small b
    C3 F6 ; # small ts
}
```

When describing a conversion table to UTF-8, codes for the UTF-8 charset should be given in the second column, for example:

```nginx
charset_map koi8-r utf-8 {
    C0 D18E ; # small yu
    C1 D0B0 ; # small a
    C2 D0B1 ; # small b
    C3 D186 ; # small ts
}
```

Full conversion tables from `koi8-r` to `windows-1251`, and from
`koi8-r` and `windows-1251` to `utf-8` are provided in the
distribution files `conf/koi-win`, `conf/koi-utf`, and
`conf/win-utf`.





### charset_types

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `charset_types` mime-type ...;                                                                             |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `charset_types text/html text/xml text/plain text/vnd.wap.wml application/javascript application/rss+xml;` |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                     |

Enables module processing in responses with the specified MIME types in addition to `text/html`. The special value `*` matches any MIME type.





### override_charset

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `override_charset` `on` | `off`;       |
|------------------------------------------------------------------------------------------|----------------------------------------|
| Default                                                                                  | `override_charset off;`                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location, if in location |

Determines whether a conversion should be performed for responses received from a proxied or a FastCGI/uwsgi/SCGI/gRPC server when the responses already carry a charset in the `Content-Type` response header field. If conversion is enabled, a charset specified in the received response is used as a source charset.

#### NOTE
If a response is received in a subrequest then the conversion from the response charset to the main request charset is always performed, regardless of the override_charset directive setting.





### source_charset

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `source_charset` charset;              |
|------------------------------------------------------------------------------------------|----------------------------------------|
| Default                                                                                  | —                                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location, if in location |

Defines the source charset of a response. If this charset is different from the charset specified in the [charset](#id1) directive, a conversion is performed.


# https://en.angie.software/angie/docs/configuration/modules/http/http_dav.md





# DAV

The module is intended for file management automation via the WebDAV protocol. The module processes HTTP and WebDAV methods PUT, DELETE, MKCOL, COPY, and MOVE.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module isn't built
by default; it must be enabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--with-http_dav_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.

#### NOTE
WebDAV clients that require additional WebDAV methods to operate will not work with this module.



## Configuration Example

```nginx
location / {
    root                  /data/www;

    client_body_temp_path /data/client_temp;

    dav_methods PUT DELETE MKCOL COPY MOVE;

    create_full_put_path  on;
    dav_access            group:rw  all:r;

    limit_except GET {
        allow 192.168.1.0/32;
        deny  all;
    }
}
```



## Directives





### create_full_put_path

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `create_full_put_path` `on` | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------------------|
| Default                                                                                  | `create_full_put_path off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                 |

The WebDAV specification only allows creating files in already existing directories. This directive allows creating all needed intermediate directories.





### dav_access

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `dav_access` users:permissions ...;   |
|------------------------------------------------------------------------------------------|---------------------------------------|
| Default                                                                                  | `dav_access user:rw;`                 |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                |

Sets access permissions for newly created files and directories, e.g.:

```nginx
dav_access user:rw group:rw all:r;
```

If any group or all access permissions are specified then user permissions may be omitted:

```nginx
dav_access group:rw all:r;
```





### dav_methods

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `dav_methods` `off` | method ...;   |
|------------------------------------------------------------------------------------------|-------------------------------------|
| Default                                                                                  | `dav_methods off;`                  |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location              |

Allows the specified HTTP and WebDAV methods. The parameter `off` denies all methods processed by this module. The following methods are supported: PUT, DELETE, MKCOL, COPY, and MOVE.

A file uploaded with the PUT method is first written to a temporary file, and then the file is renamed. Starting from version 0.8.9, temporary files and the persistent store can be put on different file systems. However, be aware that in this case a file is copied across two file systems instead of the cheap renaming operation. It is thus recommended that for any given `location` both saved files and a directory holding temporary files, set by the [client_body_temp_path](https://en.angie.software//angie/docs/configuration/modules/http/index.md#client-body-temp-path) directive, are put on the same file system.

When creating a file with the PUT method, it is possible to specify the modification date by passing it in the `Date` header field.





### min_delete_depth

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `min_delete_depth` number;   |
|------------------------------------------------------------------------------------------|------------------------------|
| Default                                                                                  | `min_delete_depth 0;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location       |

Allows the DELETE method to remove files provided that the number of elements in a request path is not less than the specified number. For example, the directive

```nginx
min_delete_depth 4;
```

allows removing files on requests

```console
/users/00/00/name
/users/00/00/name/pic.jpg
/users/00/00/page.html
```

and denies the removal of

```console
/users/00/00
```


# https://en.angie.software/angie/docs/configuration/modules/http/http_docker.md






# Docker

#### Versionadded
Added in version 1.10.0.

The module provides dynamic configuration of proxied server groups
in both [HTTP](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) and [stream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-upstream)
contexts based on Docker container labels.
For the functionality to work, a shared memory zone must be configured
in the group (see the `zone` description for [http](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone) and [stream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-zone)).

#### NOTE
The module supports working with both Docker and its alternatives,
such as Podman, which implement a compatible API.
The recommended Podman version is 4.9.3 or higher.

The module connects to the Docker daemon via API,
the interaction method with which is specified by the [docker_endpoint](#docker-endpoint) directive.
After obtaining a list of running containers,
Angie analyzes them for the presence of suitable [labels](#docker-labels).
The labels identify the target `upstream` group
and determine whether the server address includes a container port.
For each matching group, Angie adds the container address
from the selected Docker network and applies the remaining label parameters
to the corresponding `upstream` block in the Angie configuration.

#### NOTE
The same container can be added to multiple `upstream` groups.
To do this, simply specify multiple sets of labels
with different group names and values for the `port` label.

This is especially useful
if the container runs several different services on different ports —
each service can be associated with its own group.

The module then subscribes to container lifecycle events
and begins updating the proxied server configuration without reloading Angie:

- when starting a container with suitable labels,
  its internal IP address is added to the specified group;
- when stopping or removing a container,
  it is automatically removed from the group;
- when pausing a container with the **docker pause** command,
  the server is marked as `down`,
  and with **docker unpause** — as `up`.



## Configuration Example

The module's directives are always located in the `http` context,
but proxied server groups can be defined
in both the `http` context and the `stream` context.

Configuration example for `http`:

```nginx
http {

    # Examples of connection options:
    # docker_endpoint http://127.0.0.1:2375;
    # docker_endpoint https://127.0.0.1:2376;
    docker_endpoint unix:/var/run/docker.sock;

    # maximum Docker response buffer size (optional)
    # docker_max_object_size 128k;

    upstream u {

        zone z 1m; # shared memory zone is required
    }

    server {

        listen 80;
        server_name example.com;

        location / {

            proxy_pass http://u;
        }
    }
}
```

Similarly in stream context:

```nginx
http {

    # Examples of connection options:
    # docker_endpoint http://127.0.0.1:2375;
    # docker_endpoint https://127.0.0.1:2376;
    docker_endpoint unix:/var/run/docker.sock;

    # maximum Docker response buffer size (optional)
    # docker_max_object_size 128k;
}

stream {

    upstream u {

        zone z 1m;
    }

    server {

        listen 12345;
        proxy_pass u;
    }
}
```

Upon receiving an event for a container,
Angie looks for labels of the form
`angie.http.upstreams..port=` (for HTTP context)
or `angie.stream.upstreams..port=` (for stream context).
When a label is present, the container's address in the selected Docker network
is added to the corresponding proxied server group.
The network is taken from the `angie.(http|stream).upstreams..network`
label, if set for that upstream; otherwise, from the container-wide
`angie.network` label; if there's no label, the first available network is used.

If a container stops or is removed, the server is removed from the group;
if a container is paused, the server is marked as `down`.

Fragment of a `docker-compose.yml` file with labels that Angie recognizes:

```yaml
services:
  myapp:
    image: myapp:latest
    labels:
      - "angie.http.upstreams.u.port=8080"
      - "angie.network=my_bridge"
      - "angie.http.upstreams.u.weight=2"
      - "angie.http.upstreams.u.max_conns=50"
      - "angie.http.upstreams.u.max_fails=3"
      - "angie.http.upstreams.u.fail_timeout=10s"
      - "angie.http.upstreams.u.backup=true"
```



## Labels

Labels specify server parameters in the proxied server group
similar to the arguments of the `server` directive:

| Label                                                             | Purpose                                                                                                                                                                                                                                                                       |
|-------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `angie.(http|stream).upstreams..port=`  *(required)* | Adds the container to the group named ``.
Set the value to the numeric container port that Angie connects to,
or to `*` for a [portless](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-no-port) stream group (PRO). |
| `angie.network=`                                  | Name of the Docker network from which to take the container's IP address.                                                                                                                                                                                                     |
| `angie.(http|stream).upstreams..network=`   | Name of the Docker network for this proxied upstream;
takes precedence over the `angie.network` label.                                                                                                                                                                    |
| `angie.(http|stream).upstreams..weight=`                 | Value of the `weight` parameter.                                                                                                                                                                                                                                              |
| `angie.(http|stream).upstreams..max_conns=`              | Maximum number of simultaneous connections (`max_conns`).                                                                                                                                                                                                                     |
| `angie.(http|stream).upstreams..max_fails=`              | Threshold for failed attempts (`max_fails`).                                                                                                                                                                                                                                  |
| `angie.(http|stream).upstreams..fail_timeout=`           | Interval for counting failed attempts (`fail_timeout`).                                                                                                                                                                                                                       |
| `angie.(http|stream).upstreams..backup=true|false`          | Marks the server as `backup`.                                                                                                                                                                                                                                                 |
| `angie.(http|stream).upstreams..sid=`               | Sets a custom server identifier (`sid`)
for the proxied server.                                                                                                                                                                                                           |
| `angie.(http|stream).upstreams..slow_start=`          | Enables `slow_start` mode with a configurable time period.                                                                                                                                                                                                                    |



## Directives





### docker_endpoint

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `docker_endpoint` `URL`;   |
|------------------------------------------------------------------------------------------|----------------------------|
| Default                                                                                  | —                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                       |

Specifies the method of connecting to the Docker daemon and enables tracking
of container events.
The following options are supported:

| `unix:/var/run/docker.sock`             | Connection via Unix socket (e.g., `/var/run/docker.sock`).   |
|-----------------------------------------|--------------------------------------------------------------|
| `http://host:port`, `https://host:port` | Connection via HTTP or HTTPS to a remote Docker API.         |

The connection can be additionally configured using the [client](https://en.angie.software//angie/docs/configuration/modules/http/index.md#client) context,
where the module adds two named `location` blocks:

- `@docker_events` is used to receive container events;
- `@docker_containers` — to get container information.

By default, they contain the [proxy_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass) directive
with the connection address and several other optimal default settings,
to which other settings from the [Proxy](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy) module can be added.

If the directive is specified,
Angie opens a connection to Docker using the specified method,
requests a list of running containers,
analyzes their labels and processes all subsequent container events,
adding or removing servers in proxied server groups according to the labels.





### docker_max_object_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `docker_max_object_size` ``;   |
|------------------------------------------------------------------------------------------|--------------------------------------|
| Default                                                                                  | `64k`                                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                                 |

Sets the maximum buffer size
that is used for both JSON responses to Docker requests
and for the container event stream.

- For regular requests (API version, container list, container information):
  the entire response must fit in the buffer, otherwise an error occurs.
- For container events, streaming processing is used
  with buffer reuse,
  which allows processing an unlimited stream of events.

The typical value of `64k` is sufficient for approximately 25 containers.

When Docker API connection errors or response processing errors occur,
the module automatically retries at specific time intervals.
The maximum number of retry attempts for getting information
about a specific container is limited to two *additional* attempts;
after that, the module stops attempting for that container.


# https://en.angie.software/angie/docs/configuration/modules/http/http_doh.md





# DoH

#### Versionadded
Added in version 1.12.0.

Implements a DNS over HTTPS (DoH) server as defined by
[RFC 8484](https://datatracker.ietf.org/doc/html/rfc8484).
Accepts DNS queries carried over HTTP/HTTPS and proxies them to a group of DNS
servers over UDP or TCP.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by
default; it can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-http_doh_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.

A DoH client submits a DNS query either as a `GET` request, with the DNS
message passed Base64URL-encoded in the `dns` query-string argument, or as
a `POST` request, with the raw DNS message in the request body. In both
cases the media type of the DNS message is `application/dns-message`.

A DNS response accepted by the module with a nonzero `RCODE` is returned
to the client with the 200 (OK) status. The `RCODE` remains in the DNS
message and does not trigger a retry under the `invalid_response`
condition of [doh_next_upstream](#doh-next-upstream).

The [doh_transport](#doh-transport) directive controls whether queries use UDP or TCP. To
protect against off-path response spoofing, the module randomizes the query ID
sent to the DNS server and restores the client's original ID in the response.

#### NOTE
This query-ID randomization uses a non-cryptographic generator and offers
only limited protection; reach the DNS servers over a properly secured
trusted network, as recommended for the [resolver](https://en.angie.software//angie/docs/configuration/modules/http/index.md#resolver) directive.

The `Cache-Control` header field of the response is derived from the
minimum TTL of the response: it is set to `max-age=`, or to
`no-store` when no cacheable TTL can be determined.



## Configuration Example

Proxying DNS over HTTPS queries to a group of DNS servers:

```nginx
http {
    upstream dns_upstream {
        server 127.0.0.1:53;
    }

    server {
        listen 443 ssl;
        server_name dns.example.com;

        ssl_certificate     dns.example.com.crt;
        ssl_certificate_key dns.example.com.key;

        location /dns-query {
            doh_pass dns_upstream;
        }
    }
}
```



## Directives





### doh_bind

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `doh_bind` address [`transparent`] | `off`;   |
|------------------------------------------------------------------------------------------|-----------------------------------------------|
| Default                                                                                  | —                                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                        |

Makes outgoing connections to a DNS server originate from the specified local IP
address with an optional port. The parameter value can contain
[variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables). The special value `off` cancels the
effect of the [doh_bind](#doh-bind) directive inherited from the previous configuration
level, allowing the system to auto-assign the local IP address and port.

The `transparent` parameter allows outgoing connections to a DNS server to
originate from a non-local IP address, for example, from the real IP address of
a client:

```nginx
doh_bind $remote_addr transparent;
```

For this parameter to work, it is usually necessary to run Angie worker
processes with [superuser](https://en.angie.software//angie/docs/configuration/modules/core.md#user) privileges. On Linux this is not
required, as the worker processes inherit the `CAP_NET_RAW` capability from the
master process when the `transparent` parameter is specified.





### doh_buffer_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `doh_buffer_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `doh_buffer_size 16k;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                           |

Sets the `size` of the buffer used for reading the response received from
a DNS server. The `size` cannot be less than 512 bytes.





### doh_connect_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `doh_connect_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `doh_connect_timeout 60s;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                               |

Defines a timeout for establishing a connection with a DNS server.

#### NOTE
This timeout does not govern idle connections: how long an already-open one
is kept for reuse is set by [keepalive_timeout](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive-timeout) in an upstream block
whose connections are cached with [keepalive](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive). Only TCP
connections are cached, as [doh_transport](#doh-transport) describes.





### doh_max_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `doh_max_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | the size of one operating-system memory page                                                                  |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                        |

Limits the size of a DNS query message accepted from a client. The configured
`size` must be at least 12 bytes. A query shorter than 12 bytes (the size
of a DNS message header) or larger than `size` is rejected.





### doh_next_upstream

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `doh_next_upstream` `error` | `timeout` | `invalid_response` | `off` ...;   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| Default                                                                                  | `doh_next_upstream error timeout;`                                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                      |

Specifies in which cases a query should be passed to the next server in the
[upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream) group:

| `error`            | an error occurred while establishing a connection with the server,
passing a query to it, or reading the response;   |
|--------------------|--------------------------------------------------------------------------------------------------------------------------|
| `timeout`          | a timeout occurred while establishing a connection with the server,
passing a query to it, or reading the response;  |
| `invalid_response` | the server returned an invalid DNS response;                                                                             |
| `off`              | disables passing a query to the next server.                                                                             |

Passing a query to the next server can be limited by the
[number of tries](#doh-next-upstream-tries) and by
[time](#doh-next-upstream-timeout).





### doh_next_upstream_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `doh_next_upstream_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `doh_next_upstream_timeout 0;`                                                                                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                     |

Limits the time during which a query can be passed to the
[next server](#doh-next-upstream).
Setting `0` disables this limitation.





### doh_next_upstream_tries

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `doh_next_upstream_tries` number;   |
|------------------------------------------------------------------------------------------|-------------------------------------|
| Default                                                                                  | `doh_next_upstream_tries 0;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location              |

Limits the number of possible tries for passing a query to the
[next server](#doh-next-upstream).
Setting `0` disables this limitation.





### doh_pass

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `doh_pass` address;      |
|------------------------------------------------------------------------------------------|--------------------------|
| Default                                                                                  | —                        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | location, if in location |

Sets the address of a DNS server to which DNS queries are proxied. The address
can be specified as a domain name or IP address with a port:

```nginx
doh_pass 127.0.0.1:53;
```

or as a [server group](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream):

```nginx
doh_pass dns_upstream;
```

Queries are forwarded to the server over UDP or TCP, as configured by the
[doh_transport](#doh-transport) directive. Only one [doh_pass](#doh-pass) directive can be specified
in a location.





### doh_read_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `doh_read_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `doh_read_timeout 60s;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                            |

Defines a timeout for reading a response from a DNS server. The timeout is set
only between two successive read operations, not for the transmission of the
whole response. If the DNS server does not transmit anything within this time,
the connection is closed.





### doh_send_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `doh_send_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `doh_send_timeout 60s;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                            |

Sets a timeout for transmitting a request to a DNS server. The timeout is set
only between two successive write operations, not for the transmission of the
whole request. If the DNS server does not receive anything within this time, the
connection is closed.





### doh_socket_keepalive

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `doh_socket_keepalive` `on` | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------------------|
| Default                                                                                  | `doh_socket_keepalive off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                 |

Enables the `SO_KEEPALIVE` socket option for outgoing connections to a
DNS server. With `off`, the operating system's socket settings remain in
effect.





### doh_transport

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `doh_transport` `tcp` | `udp` | `auto`;   |
|------------------------------------------------------------------------------------------|-------------------------------------------|
| Default                                                                                  | `doh_transport auto;`                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                    |

Selects the transport protocol used to forward DNS queries to a DNS server:

| `auto`   | if the upstream's [keepalive](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive) cache holds a free TCP
connection, the query is sent over it (TCP); otherwise it is first sent
over UDP and retried over TCP if the server responds with a truncated
message (the `TC` flag is set);   |
|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `udp`    | queries are sent over UDP only; a truncated response is treated as an
error, and the query is not retried over TCP;                                                                                                                                                                                                                         |
| `tcp`    | queries are sent over TCP only.                                                                                                                                                                                                                                                                                                                 |


# https://en.angie.software/angie/docs/configuration/modules/http/http_empty_gif.md





# Empty GIF

The module emits a single-pixel transparent GIF.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by
default; it can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-http_empty_gif_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
location = /_.gif {
    empty_gif;
}
```



## Directives





### empty_gif

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `empty_gif`;   |
|------------------------------------------------------------------------------------------|----------------|
| Default                                                                                  | —              |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | location       |

Enables emitting a single-pixel transparent GIF in the containing location.


# https://en.angie.software/angie/docs/configuration/modules/http/http_fastcgi.md





# FastCGI

The module allows passing requests to a FastCGI server.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by
default; it can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-http_fastcgi_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
location / {
    fastcgi_pass  localhost:9000;
    fastcgi_index index.php;

    fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name;
    fastcgi_param QUERY_STRING    $query_string;
    fastcgi_param REQUEST_METHOD  $request_method;
    fastcgi_param CONTENT_TYPE    $content_type;
    fastcgi_param CONTENT_LENGTH  $content_length;
}
```



## Directives





### fastcgi_bind

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_bind` address [`transparent`] | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------------------------|
| Default                                                                                  | —                                                 |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                            |

Makes outgoing connections to a FastCGI server originate from the specified local IP address with an optional port. Parameter value can contain [variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables). The special value `off` cancels the effect of the fastcgi_bind directive inherited from the previous configuration level, which allows the system to auto-assign the local IP address and port.

By default, this value is evaluated once when the request is initialized, before
a FastCGI server is selected. In Angie PRO, evaluation happens after each
FastCGI server selection (including retries), so the bind address can depend on
the selected server; for example, via the `$upstream_current_addr`
variable. If the evaluated value is empty, no binding is made.

The `transparent` parameter allows outgoing connections to a FastCGI
server originate from a non-local IP address, for example, from a real IP
address of a client:

```nginx
fastcgi_bind $remote_addr transparent;
```

For this parameter to work,
Angie worker processes usually need to run
with [superuser](https://en.angie.software//angie/docs/configuration/modules/core.md#user) privileges.
On Linux, this is not required:
if the `transparent` parameter is specified,
worker processes inherit the CAP_NET_RAW capability from the master process.

#### NOTE
The kernel routing table should also be configured
to intercept network traffic from the FastCGI server.





### fastcgi_buffer_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_buffer_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `fastcgi_buffer_size 4k|8k;`                                                                                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                               |

Sets the size of the buffer used for reading the first part of the response received from the FastCGI server. This part usually contains a small response header. By default, the buffer size is equal to one memory page. This is either 4K or 8K, depending on a platform. It can be made smaller, however.





### fastcgi_buffering

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_buffering` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-------------------------------------|
| Default                                                                                  | `fastcgi_buffering on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location              |

Enables or disables buffering of responses from the FastCGI server.

| `on`   | Angie receives a response from the FastCGI server as soon as possible, saving it into the buffers set by the [fastcgi_buffer_size](#fastcgi-buffer-size) and [fastcgi_buffers](#fastcgi-buffers) directives. Sending to the client is performed in parallel: filled buffers are passed for sending, but their total size is limited by [fastcgi_busy_buffers_size](#fastcgi-busy-buffers-size). If a buffer is not completely filled, it is not passed for sending unless it contains the last part of the response. Therefore, buffered reading is not suitable when you need immediate delivery of every few bytes. If the whole response does not fit into memory, a part of it can be saved to a [temporary file](#fastcgi-temp-path) on the disk. Writing to temporary files is controlled by the [fastcgi_max_temp_file_size](#fastcgi-max-temp-file-size) and [fastcgi_temp_file_write_size](#fastcgi-temp-file-write-size) directives.   |
|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off`  | The response is passed to a client immediately as it is received. Angie works in a "read — send" loop and does not wait for the buffer to fill completely: for example, 10 bytes read from a 4K buffer are sent right away. At the same time, if the entire response fits into the buffer, Angie can read it in full. The maximum size of the data that Angie can receive from the server at a time is set by the [fastcgi_buffer_size](#fastcgi-buffer-size) directive. With `off`, [fastcgi_limit_rate](#fastcgi-limit-rate) does not work.                                                                                                                                                                                                                                                                                                                                                                                                    |

Buffering can also be enabled or disabled by passing "yes" or "no" in the `X-Accel-Buffering` response header field. This capability can be disabled using the [fastcgi_ignore_headers](#fastcgi-ignore-headers) directive.





### fastcgi_buffers

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_buffers` number [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `fastcgi_buffers 8 4k|8k;`                                                                                              |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                  |

Sets the number and size of the buffers used for reading a response from the FastCGI server, for a single connection.

By default, the buffer size is equal to one memory page. This is either 4K or 8K, depending on a platform.





### fastcgi_busy_buffers_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_busy_buffers_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `fastcgi_busy_buffers_size 8k|16k;`                                                                                        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                     |

When [buffering](#fastcgi-buffering) of responses from the FastCGI server is enabled, limits the total size of buffers that can be busy sending a response to the client while the response is not yet fully read. In the meantime, the rest of the buffers can be used for reading the response and, if needed, buffering part of the response to a temporary file. By default, size is limited by the size of two buffers set by the [fastcgi_buffer_size](#fastcgi-buffer-size) and [fastcgi_buffers](#fastcgi-buffers) directives.





### fastcgi_cache

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_cache` zone | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------|
| Default                                                                                  | `fastcgi_cache off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location          |

Defines a shared memory zone used for caching. The same zone can be used in several places. Parameter value can contain variables. The `off` parameter disables caching inherited from the previous configuration level.

#### NOTE
When using [fastcgi_cache](#fastcgi-cache),
you typically need to also set the [fastcgi_cache_valid](#fastcgi-cache-valid) directive
to explicitly specify the caching time for responses.
If it's not set, Angie doesn't use default values
but determines the response caching time
based on HTTP response headers from the server in the following priority order:

1. The `X-Accel-Expires` header (highest priority).
2. The `Cache-Control` header
   with `max-age` or `s-maxage` parameters.
3. The `Expires` header.

If none of these headers contain valid values or are not present at all,
the response will not be cached because its expiration time cannot be determined.





### fastcgi_cache_background_update

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_cache_background_update` `on` | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------------------------|
| Default                                                                                  | `fastcgi_cache_background_update off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                            |

Allows starting a background subrequest to update an expired cache item, while a stale cached response is returned to the client. Note that it is necessary to [allow](#fastcgi-cache-use-stale-updating) the usage of a stale cached response when it is being updated.





### fastcgi_cache_bypass

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_cache_bypass` string ...;   |
|------------------------------------------------------------------------------------------|--------------------------------------|
| Default                                                                                  | —                                    |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location               |

Defines conditions under which the response will not be taken from a cache. If at least one value of the string parameters is not empty and is not equal to "0" then the response will not be taken from the cache:

```nginx
fastcgi_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
fastcgi_cache_bypass $http_pragma    $http_authorization;
```

Parameter values can contain variables.

Can be used together with the [fastcgi_no_cache](#fastcgi-no-cache) directive.





### fastcgi_cache_key

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_cache_key` string;   |
|------------------------------------------------------------------------------------------|-------------------------------|
| Default                                                                                  | —                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location        |

Defines a key for caching. The key can contain variables. For example

```nginx
fastcgi_cache_key localhost:9000$request_uri;
```





### fastcgi_cache_lock

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_cache_lock` `on` | `off`;   |
|------------------------------------------------------------------------------------------|--------------------------------------|
| Default                                                                                  | `fastcgi_cache_lock off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location               |

When enabled, only one request at a time will be allowed to populate a new cache element identified according to the [fastcgi_cache_key](#fastcgi-cache-key) directive by passing a request to a FastCGI server. Other requests of the same cache element will either wait for a response to appear in the cache or the cache lock for this element to be released, up to the time set by the [fastcgi_cache_lock_timeout](#fastcgi-cache-lock-timeout) directive.





### fastcgi_cache_lock_age

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_cache_lock_age` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `fastcgi_cache_lock_age 5s;`                                                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                  |

If the last request passed to the FastCGI server for populating a new cache element has not completed for the specified time, one more request may be passed to the FastCGI server.





### fastcgi_cache_lock_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_cache_lock_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `fastcgi_cache_lock_timeout 5s;`                                                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                      |

Sets a timeout for [fastcgi_cache_lock](#fastcgi-cache-lock). When the time expires, the request will be passed to the FastCGI server, however, the response will not be cached.





### fastcgi_cache_max_range_offset

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_cache_max_range_offset` number;   |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| Default                                                                                  | —                                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                     |

Sets an offset in bytes for byte-range requests. If the range is beyond the offset, the range request will be passed to the FastCGI server and the response will not be cached.





### fastcgi_cache_methods

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_cache_methods` `GET` | `HEAD` | `POST` ...;   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------|
| Default                                                                                  | `fastcgi_cache_methods GET HEAD;`                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                 |

If the client request method is listed in this directive then the response will be cached. "GET" and "HEAD" methods are always added to the list, though it is recommended to specify them explicitly. See also the [fastcgi_no_cache](#fastcgi-no-cache) directive.





### fastcgi_cache_min_uses

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_cache_min_uses` number;   |
|------------------------------------------------------------------------------------------|------------------------------------|
| Default                                                                                  | `fastcgi_cache_min_uses 1;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location             |

Sets the number of requests after which the response will be cached.

#### WARNING
Cache metadata is stored in shared memory. Manually deleting cache files does
not reset the counters and may lead to unpredictable behavior. To
completely reset the cache, stop the server, delete the cache directory, and start again.

#### NOTE
Third-party cache purge modules (e.g., [Cache Purge](https://en.angie.software//angie/docs/configuration/modules/external-modules/cache-purge.md#external-cache-purge)) only delete
files but do not reset the fastcgi_cache_min_uses counter. The directive
is intended to protect the cache from pollution by infrequent requests, and resetting
the counter on purge may negatively affect performance.





### fastcgi_cache_path

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_cache_path` path [`levels=`levels] [`use_temp_path=``on` | `off`] `keys_zone=`name:size[:`file=`file] [`inactive=`time] [`max_size=`size] [`min_free=`size] [`manager_files=`number] [`manager_sleep=`time] [`manager_threshold=`time] [`loader_files=`number] [`loader_sleep=`time] [`loader_threshold=`time];   |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | —                                                                                                                                                                                                                                                                                                                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                                                                                                                                                                                                                     |

Sets the path and other parameters of a cache. Cache data are stored in files. Both the key and file name in a cache are a result of applying the MD5 function to the proxied URL.

| `levels`   | defines hierarchy levels of a cache: from 1 to 3, each level accepts values 1 or 2.   |
|------------|---------------------------------------------------------------------------------------|

For example, in the following configuration:

```nginx
fastcgi_cache_path /data/angie/cache levels=1:2 keys_zone=one:10m;
```

file names in a cache will look like this:

```nginx
/data/angie/cache/c/29/b7f54b2df7773722d382f4809d65029c
```

A cached response is first written to a temporary file, and then the file is renamed. Temporary files and the cache can be put on different file systems. However, be aware that in this case a file is copied across two file systems instead of the cheap renaming operation. It is thus recommended that for any given location both cache and a directory holding temporary files are put on the same file system.

| `use_temp_path=on` | `off`   | determines the directory to be used for temporary files                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
|------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `on`                         | If the parameter is not specified or set to `on`, the directory specified by the [fastcgi_temp_path](#fastcgi-temp-path) directive for the given location will be used                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `off`                        | temporary files will be placed directly in the cache directory                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `keys_zone`                  | Sets the name and size of the shared memory zone for storing all active keys and information about data. Cache metadata is stored in shared memory.

The zone size is specified in bytes and must be at least two system
memory pages. The `k` and `m` suffixes are also accepted;
unlike `max_size`, this parameter does not accept `g`.

A zone of 1 megabyte is sufficient to store about 8000 keys.

When an optional file is specified with `keys_zone`,
Angie dumps the contents of this zone to disk
when the main process terminates
and attempts to restore it at the same memory address
on the next [startup](https://en.angie.software//angie/docs/configuration/runtime.md#runtime)
or after [binary upgrade](https://en.angie.software//angie/docs/configuration/runtime.md#service-upgrade),
to ensure more reliable data persistence
and reduce cache loading time.

If the zone cannot be restored due to a change in its size,
binary version incompatibility, or other reasons,
Angie will log a warning (`failed to restore zone at address`)
and will not use the zone restoration mechanism.
Instead, the incompatible file will be renamed to `.old`;
you can either delete it,
or restore its name and revert Angie to the configuration and version
in which this file was originally created.

#### WARNING
Make sure the path to the file is specified correctly
and has the necessary access permissions for Angie to use,
and is protected from unauthorized access;
relative paths are based on the [prefix](https://en.angie.software//angie/docs/installation/sourcebuild.md#paths). |
| `inactive`                   | If cached data is not accessed within the time set by this parameter, it is removed, regardless of its freshness; each access resets this timer. This differs from the size-based eviction performed by the **cache manager** described below: inactivity-based removal applies even when the cache is below `max_size`, and it ignores the validity periods configured with [fastcgi_cache_valid](#fastcgi-cache-valid).

By default, `inactive` is 10 minutes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

A special **cache manager** process monitors the maximum cache size, and the minimum amount of free space on the file system with cache. When the size is exceeded or there is not enough free space, it removes the least recently used data. The data is removed in iterations.

| `max_size`          | maximum threshold value for cache size

The value is specified in bytes; the `k`, `m`, and
`g` suffixes are also accepted.
By default, the cache size is not limited.                                                                                                                                                                                                          |
|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `min_free`          | minimum threshold value for free space on the file system with cache

The value is specified in the same units as `max_size`.
The default value `0` disables free space monitoring.

On platforms that do not support querying file system statistics,
the parameter is ignored, and Angie logs the warning
`min_free is not supported on this platform, ignored`. |
| `manager_files`     | limits the number of items to be deleted during one iteration

By default, `100`.                                                                                                                                                                                                                                                                                                      |
| `manager_threshold` | limits the duration of one iteration

By default, `200` milliseconds                                                                                                                                                                                                                                                                                                                   |
| `manager_sleep`     | configures a pause between iterations

By default, `50` milliseconds                                                                                                                                                                                                                                                                                                                   |

A minute after Angie starts, the special **cache loader** process is activated. It loads information about previously cached data stored on file system into a cache zone. The loading is also done in iterations.

| `loader_files`     | maximum number of cache items to load in one iteration

Default: `100`              |
|--------------------|---------------------------------------------------------------------------------------------|
| `loader_threshold` | limits the time of one iteration

Default: `200` milliseconds                       |
| `loader_sleep`     | time for which a pause is maintained between iterations

Default: `50` milliseconds |





### fastcgi_cache_revalidate

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_cache_revalidate` `on` | `off`;   |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| Default                                                                                  | `fastcgi_cache_revalidate off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                     |

Enables revalidation of expired cache items using conditional requests with the `If-Modified-Since` and `If-None-Match` header fields.





### fastcgi_cache_use_stale

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_cache_use_stale` `error` | `timeout` | `invalid_header` | `updating` | `http_500` | `http_503` | `http_403` | `http_429` | `off` ...;   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `fastcgi_cache_use_stale off;`                                                                                                                   |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                                           |

Determines in which cases a stale cached response can be used when an error occurs during communication with the FastCGI server. The directive's parameters match the parameters of the [fastcgi_next_upstream](#fastcgi-next-upstream) directive.

| `error`    | permits using a stale cached response if a FastCGI server cannot be selected for processing a request.                                                                                           |
|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `updating` | an additional parameter that permits using a stale cached response if it is currently being updated. This allows minimizing the number of accesses to FastCGI servers when updating cached data. |

The use of a stale cached response can also be permitted directly in the response header for a specified number of seconds after the response became stale.

* The [stale-while-revalidate](https://datatracker.ietf.org/doc/html/rfc5861#section-3) extension of the `Cache-Control` header field permits using a stale cached response if it is currently being updated.
* The [stale-if-error](https://datatracker.ietf.org/doc/html/rfc5861#section-4) extension of the `Cache-Control` header field permits using a stale cached response in case of an error.

#### NOTE
This method has lower priority than setting the directive parameters.

To minimize the number of accesses to FastCGI servers when populating a new cache element, the [fastcgi_cache_lock](#fastcgi-cache-lock) directive can be used.





### fastcgi_cache_valid

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_cache_valid` [code ...] [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | —                                                                                                                               |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                          |

Sets caching time for different response codes. For example, the following directives

```nginx
fastcgi_cache_valid 200 302 10m;
fastcgi_cache_valid 404      1m;
```

set 10 minutes of caching for responses with codes 200 and 302 and 1 minute for responses with code 404.

If only caching time is specified,

```nginx
fastcgi_cache_valid 5m;
```

then only 200, 301, and 302 responses are cached.

In addition, it can be specified to cache any responses using the `any` parameter:

```nginx
fastcgi_cache_valid 200 302 10m;
fastcgi_cache_valid 301      1h;
fastcgi_cache_valid any      1m;
```

#### NOTE
Parameters of caching can also be set directly in the response header. This has higher priority than setting of caching time using the directive.

* The `X-Accel-Expires` header field sets caching time of a response in seconds. The zero value disables caching for a response. If the value starts with the @ prefix, it sets an absolute time in seconds since Epoch, up to which the response may be cached.
* If the header does not include the `X-Accel-Expires` field, parameters of caching may be set in the header fields `Expires` or `Cache-Control`.
* If the header includes the `Set-Cookie` field, such a response will not be cached.
* If the header includes the `Vary` field with the special value "\*", such a response will not be cached. If the header includes the `Vary` field with another value, such a response will be cached taking into account the corresponding request header fields.

Processing of one or more of these response header fields can be disabled using the [fastcgi_ignore_headers](#fastcgi-ignore-headers) directive.





### fastcgi_catch_stderr

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_catch_stderr` string;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | —                                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location           |

Sets a string to search for in the error stream of a response received from a FastCGI server. If the string is found then it is considered that the FastCGI server has returned an [invalid](#fastcgi-next-upstream) response. This allows handling application errors in Angie, for example:

```nginx
location /php/ {
    fastcgi_pass backend:9000;
    ...
    fastcgi_catch_stderr "PHP Fatal error";
    fastcgi_next_upstream error timeout invalid_header;
}
```





### fastcgi_connect_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_connect_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `fastcgi_connect_timeout 60s;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                   |

Defines a timeout for establishing a connection with a FastCGI server. It should be noted that this timeout cannot usually exceed 75 seconds.

#### NOTE
This timeout does not govern idle connections: how long an already-open one
is kept for reuse is set by [keepalive_timeout](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive-timeout) in an upstream block
whose connections are cached with [keepalive](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive). FastCGI
connections are cached only with [fastcgi_keep_conn](#fastcgi-keep-conn) enabled.





### fastcgi_connection_drop

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_connection_drop` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units) | `on` | `off`;   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `fastcgi_connection_drop off;`                                                                                                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                                  |

Enables termination of all active connections to the proxied server after it has been
removed from the group or marked as permanently unavailable by a [reresolve](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve) process or the [API command](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-config-methods)
`DELETE`.
Idle connections in the [cache](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive) are not affected.

A connection is terminated when the next read or write event is processed for
either the client or the proxied server.

Setting time enables a connection termination [timeout](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);
with `on` set, connections are dropped immediately.





### fastcgi_force_ranges

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_force_ranges` `on` | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------------------|
| Default                                                                                  | `fastcgi_force_ranges off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                 |

Enables byte-range support for both cached and uncached responses from the FastCGI server regardless of the `Accept-Ranges` field in these responses.





### fastcgi_hide_header

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_hide_header` field;   |
|------------------------------------------------------------------------------------------|--------------------------------|
| Default                                                                                  | —                              |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location         |

By default, Angie does not pass the header fields `Status` and `X-Accel-...` from the response of a FastCGI server to a client. The `fastcgi_hide_header` directive sets additional fields that will not be passed. If, on the contrary, the passing of fields needs to be permitted, the [fastcgi_pass_header](#fastcgi-pass-header) directive can be used.





### fastcgi_ignore_client_abort

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_ignore_client_abort` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-----------------------------------------------|
| Default                                                                                  | `fastcgi_ignore_client_abort off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                        |

Determines whether the connection with a FastCGI server should be closed when a client closes the connection without waiting for a response.





### fastcgi_ignore_headers

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_ignore_headers` field;   |
|------------------------------------------------------------------------------------------|-----------------------------------|
| Default                                                                                  | —                                 |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location            |

Disables processing of certain response header fields from the FastCGI server. The following fields can be ignored: `X-Accel-Redirect`, `X-Accel-Expires`, `X-Accel-Limit-Rate`, `X-Accel-Buffering`, `X-Accel-Charset`, `Expires`, `Cache-Control`, `Set-Cookie`, and `Vary`.

If not disabled, processing of these header fields has the following effect:

* `X-Accel-Expires`, `Expires`, `Cache-Control`, `Set-Cookie`, and `Vary` set the [parameters](#fastcgi-cache-valid) of response caching;
* `X-Accel-Redirect` performs an [internal redirect](https://en.angie.software//angie/docs/configuration/modules/http/index.md#internal) to the specified URI;
* `X-Accel-Limit-Rate` sets the [rate limit](https://en.angie.software//angie/docs/configuration/modules/http/index.md#limit-rate) for transmission of a response to a client;
* `X-Accel-Buffering` enables or disables [buffering](#fastcgi-buffering) of a response;
* `X-Accel-Charset` sets the desired [charset](https://en.angie.software//angie/docs/configuration/modules/http/http_charset.md#id1) of a response.





### fastcgi_index

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_index` name;   |
|------------------------------------------------------------------------------------------|-------------------------|
| Default                                                                                  | —                       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location  |

Sets a file name that will be appended after a URI that ends with a slash, in the value of the [$fastcgi_script_name](#v-fastcgi-script-name) variable. For example, with these settings

```nginx
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name;
```

and the `/page.php` request, the `SCRIPT_FILENAME` parameter will be equal to `/home/www/scripts/php/page.php`, and with the `/` request it will be equal to `/home/www/scripts/php/index.php`.





### fastcgi_intercept_errors

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_intercept_errors` `on` | `off`;   |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| Default                                                                                  | `fastcgi_intercept_errors off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                     |

Determines whether FastCGI server responses with codes greater than or equal to 300 should be passed to a client or be intercepted and redirected to Angie for processing with the [error_page](https://en.angie.software//angie/docs/configuration/modules/http/index.md#error-page) directive.





### fastcgi_keep_conn

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_keep_conn` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-------------------------------------|
| Default                                                                                  | `fastcgi_keep_conn off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location              |

By default, a FastCGI server will close a connection right after sending the response. However, when this directive is set to the value `on`, Angie will instruct a FastCGI server to keep connections open. This is necessary, in particular, for [keepalive](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive) connections to FastCGI servers to function.





### fastcgi_limit_rate

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_limit_rate` rate;   |
|------------------------------------------------------------------------------------------|------------------------------|
| Default                                                                                  | `fastcgi_limit_rate 0;`      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location       |

Limits the speed of reading the response from the proxied server.
The rate is specified in bytes per second and can contain variables.

| `0`   | disables rate limiting   |
|-------|--------------------------|

#### NOTE
The limit is set per a request, and so if Angie simultaneously opens two connections to the FastCGI server, the overall rate will be twice as much as the specified limit. The limitation works only if [buffering](#fastcgi-buffering) of responses from the FastCGI server is enabled.





### fastcgi_max_temp_file_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_max_temp_file_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `fastcgi_max_temp_file_size 1024m;`                                                                                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                      |

When [buffering](#fastcgi-buffering) of responses from the FastCGI server is enabled, and the entire response does not fit into the buffers set by the [fastcgi_buffer_size](#fastcgi-buffer-size) and [fastcgi_buffers](#fastcgi-buffers) directives, a part of the response can be saved to a temporary file. This directive sets the maximum size of the temporary file. The size of data written to the temporary file at a time is set by the [fastcgi_temp_file_write_size](#fastcgi-temp-file-write-size) directive.

| `0`   | disables buffering of responses to temporary files   |
|-------|------------------------------------------------------|

#### NOTE
This restriction does not apply to responses that will be [cached](#fastcgi-cache) or [stored](#fastcgi-store) on disk.





### fastcgi_next_upstream

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_next_upstream` `error` | `timeout` | `invalid_header` | `http_500` | `http_503` | `http_403` | `http_404` | `http_429` | `non_idempotent` | `off` ...;   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `fastcgi_next_upstream error timeout;`                                                                                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                                                            |

Specifies in which cases a request should be passed to the next server:

| `error`          | an error occurred while establishing a connection with the server, passing a request to it, or reading the response header;                                                                                                                                                                             |
|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `timeout`        | a timeout has occurred while establishing a connection with the server, passing a request to it, or reading the response header;                                                                                                                                                                        |
| `invalid_header` | a server returned an empty or invalid response;                                                                                                                                                                                                                                                         |
| `http_500`       | a server returned a response with the code 500;                                                                                                                                                                                                                                                         |
| `http_503`       | a server returned a response with the code 503;                                                                                                                                                                                                                                                         |
| `http_403`       | a server returned a response with the code 403;                                                                                                                                                                                                                                                         |
| `http_404`       | a server returned a response with the code 404;                                                                                                                                                                                                                                                         |
| `http_429`       | a server returned a response with the code 429;                                                                                                                                                                                                                                                         |
| `non_idempotent` | normally, requests with a [non-idempotent](https://datatracker.ietf.org/doc/html/rfc7231#section-4.2.2) method
(`POST`, `LOCK`, `PATCH`) are not passed to the next
server if a request has been sent to an upstream server; enabling this
option explicitly allows retrying such requests; |
| `off`            | disables passing a request to the next server.                                                                                                                                                                                                                                                          |

#### NOTE
One should bear in mind that passing a request to the next server is only possible if nothing has been sent to a client yet. That is, if an error or timeout occurs in the middle of the transferring of a response, fixing this is impossible.

The directive also defines what is considered an [unsuccessful attempt](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) of communication with a server.

| `error`

`timeout`

`invalid_header`   | always considered unsuccessful attempts, even if they are not specified in the directive   |
|--------------------------------------------------------|--------------------------------------------------------------------------------------------|
| `http_500`

`http_503`

`http_429`     | considered unsuccessful attempts only if they are specified in the directive               |
| `http_403`

`http_404`                         | never considered unsuccessful attempts                                                     |

Passing a request to the next server can be limited by the [number of tries](#fastcgi-next-upstream-tries) and by [time](#fastcgi-next-upstream-timeout).





### fastcgi_next_upstream_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_next_upstream_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `fastcgi_next_upstream_timeout 0;`                                                                                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                         |

Limits the time during which a request can be passed to the [next server](#fastcgi-next-upstream).

| `0`   | turns off this limitation   |
|-------|-----------------------------|





### fastcgi_next_upstream_tries

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_next_upstream_tries` number;   |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| Default                                                                                  | `fastcgi_next_upstream_tries 0;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                  |

Limits the number of possible tries for passing a request to the [next server](#fastcgi-next-upstream).

| `0`   | turns off this limitation   |
|-------|-----------------------------|





### fastcgi_no_cache

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_no_cache` string ...;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | —                                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location           |

Defines conditions under which the response will not be saved to a cache. If at least one value of the string parameters is not empty and is not equal to "0" then the response will not be saved:

```nginx
fastcgi_no_cache $cookie_nocache $arg_nocache$arg_comment;
fastcgi_no_cache $http_pragma    $http_authorization;
```

Parameter values can contain variables.

Can be used along with the [fastcgi_cache_bypass](#fastcgi-cache-bypass) directive.





### fastcgi_param

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_param` parameter value [`if_not_empty`];   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------|
| Default                                                                                  | —                                                   |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                              |

Sets a parameter that should be passed to the FastCGI server. The value can contain variables. These directives are inherited from the previous configuration level if and only if there are no fastcgi_param directives defined on the current level.

#### NOTE
In the standard `fastcgi.conf` and `fastcgi_params` files shipped
with Angie, `REQUEST_METHOD` is set to `$upstream_request_method`.
This ensures that when caching converts `HEAD` to `GET`, the
upstream request method reflects that conversion.

The following example shows the minimum required settings for PHP:

```nginx
fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name;
fastcgi_param QUERY_STRING    $query_string;
```

The SCRIPT_FILENAME parameter is used in PHP for determining the script name, and the QUERY_STRING parameter is used to pass request parameters.

For scripts that process POST requests, the following three parameters are also required:

```nginx
fastcgi_param REQUEST_METHOD  $request_method;
fastcgi_param CONTENT_TYPE    $content_type;
fastcgi_param CONTENT_LENGTH  $content_length;
```

If PHP was built with the `--enable-force-cgi-redirect` configuration parameter, the REDIRECT_STATUS parameter should also be passed with the value "200":

```nginx
fastcgi_param REDIRECT_STATUS 200;
```

If the directive is specified with `if_not_empty` then such a parameter will be passed to the server only if its value is not empty:

```nginx
fastcgi_param HTTPS           $https if_not_empty;
```





### fastcgi_pass

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_pass` address;   |
|------------------------------------------------------------------------------------------|---------------------------|
| Default                                                                                  | —                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | location, if in location  |

Sets the address of a FastCGI server. The address can be specified as a domain name or IP address, and a port:

```nginx
fastcgi_pass localhost:9000;
```

or as a UNIX-domain socket path:

```nginx
fastcgi_pass unix:/tmp/fastcgi.socket;
```

If a domain name resolves to several addresses, all of them will be used in a round-robin fashion. In addition, an address can be specified as a [server group](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream).

Parameter value can contain variables. In this case, if an address is specified as a domain name, the name is searched among the described [server groups](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream), and, if not found, is determined using a [resolver](https://en.angie.software//angie/docs/configuration/modules/http/index.md#resolver).

#### NOTE
If `fastcgi_pass` is placed in a `location` whose prefix ends with a slash
(for example, `location /name/`),
and the [auto_redirect](https://en.angie.software//angie/docs/configuration/modules/http/index.md#auto-redirect) directive is set to `default`,
requests without a trailing slash will be redirected (`/name -> /name/`).





### fastcgi_pass_header

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_pass_header` field;   |
|------------------------------------------------------------------------------------------|--------------------------------|
| Default                                                                                  | —                              |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location         |

Permits passing [otherwise disabled](#fastcgi-hide-header) header fields from a FastCGI server to a client.





### fastcgi_pass_request_body

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_pass_request_body` `on` | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| Default                                                                                  | `fastcgi_pass_request_body on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                      |

Indicates whether the original request body is passed to the FastCGI server. See also the [fastcgi_pass_request_headers](#fastcgi-pass-request-headers) directive.





### fastcgi_pass_request_headers

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_pass_request_headers` `on` | `off`;   |
|------------------------------------------------------------------------------------------|------------------------------------------------|
| Default                                                                                  | `fastcgi_pass_request_headers on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                         |

Indicates whether the header fields of the original request are passed to the FastCGI server. See also the [fastcgi_pass_request_body](#fastcgi-pass-request-body) directive.





### fastcgi_read_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_read_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `fastcgi_read_timeout 60s;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                |

Defines a timeout for reading a response from the FastCGI server. The timeout is set only between two successive read operations, not for the transmission of the whole response. If the FastCGI server does not transmit anything within this time, the connection is closed.





### fastcgi_request_buffering

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_request_buffering` `on` | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| Default                                                                                  | `fastcgi_request_buffering on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                      |

Enables or disables buffering of a client request body.

| `on`   | the entire request body is [read](https://en.angie.software//angie/docs/configuration/modules/http/index.md#client-body-buffer-size) from the client before sending the request to a FastCGI server.                     |
|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off`  | the request body is sent to the FastCGI server immediately as it is received. In this case, the request cannot be passed to the [next server](#fastcgi-next-upstream) if Angie already started sending the request body. |





### fastcgi_send_lowat

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_send_lowat` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `fastcgi_send_lowat 0;`                                                                                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                              |

If the directive is set to a non-zero value, Angie will try to minimize the number of send operations on outgoing connections to a FastCGI server by using either NOTE_LOWAT flag of the [kqueue](https://en.angie.software//angie/docs/configuration/processing.md#kqueue) method, or the SO_SNDLOWAT socket option, with the specified size.

#### NOTE
This directive is ignored on Linux, Solaris, and Windows.





### fastcgi_send_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_send_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `fastcgi_send_timeout 60s;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                |

Sets a timeout for transmitting a request to the FastCGI server. The timeout is set only between two successive write operations, not for the transmission of the whole request. If the FastCGI server does not receive anything within this time, the connection is closed.





### fastcgi_socket_keepalive

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_socket_keepalive` `on` | `off`;   |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| Default                                                                                  | `fastcgi_socket_keepalive off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                     |

Configures the "TCP keepalive" behavior for outgoing connections to a FastCGI server.

| `off`   | By default, the operating system's settings are in effect for the socket.   |
|---------|-----------------------------------------------------------------------------|
| `on`    | the SO_KEEPALIVE socket option is turned on for the socket.                 |





### fastcgi_split_path_info

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_split_path_info` regex;   |
|------------------------------------------------------------------------------------------|------------------------------------|
| Default                                                                                  | —                                  |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | location                           |

Defines a regular expression that captures a value for the [$fastcgi_path_info](#v-fastcgi-path-info) variable. The regular expression should have two captures: the first becomes a value of the [$fastcgi_script_name](#v-fastcgi-script-name) variable, the second becomes a value of the [$fastcgi_path_info](#v-fastcgi-path-info) variable. For example, with these settings

```default
location ~ ^(.+\.php)(.*)$ {
    fastcgi_split_path_info       ^(.+\.php)(.*)$;
    fastcgi_param SCRIPT_FILENAME /path/to/php$fastcgi_script_name;
    fastcgi_param PATH_INFO       $fastcgi_path_info;
```

and the `/show.php/article/0001` request, the SCRIPT_FILENAME parameter will be equal to `/path/to/php/show.php`,
and the PATH_INFO parameter will be equal to `/article/0001`.





### fastcgi_store

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_store` `on` | `off` | string;   |
|------------------------------------------------------------------------------------------|------------------------------------------|
| Default                                                                                  | `fastcgi_store off;`                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                   |

Enables saving of files to a disk.

| `on`   | saves files with paths corresponding to the directives [alias](https://en.angie.software//angie/docs/configuration/modules/http/index.md#alias) or [root](https://en.angie.software//angie/docs/configuration/modules/http/index.md#root).   |
|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off`  | disables saving of files                                                                                                                                                                                                                     |

In addition, the file name can be set explicitly using the string with variables:

```nginx
fastcgi_store /data/www$original_uri;
```

The modification time of files is set according to the received `Last-Modified` response header field. The response is first written to a temporary file, and then the file is renamed. Temporary files and the persistent store can be put on different file systems. However, be aware that in this case a file is copied across two file systems instead of the cheap renaming operation. It is thus recommended that for any given location both saved files and a directory holding temporary files, set by the [fastcgi_temp_path](#fastcgi-temp-path) directive, are put on the same file system.

This directive can be used to create local copies of static unchangeable files, e.g.:

```nginx
location /images/ {
    root                 /data/www;
    error_page           404 = /fetch$uri;
}

location /fetch/ {
    internal;

    fastcgi_pass         backend:9000;
    ...

    fastcgi_store        on;
    fastcgi_store_access user:rw group:rw all:r;
    fastcgi_temp_path    /data/temp;

    alias                /data/www/;
}
```





### fastcgi_store_access

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_store_access` users:permissions ...;   |
|------------------------------------------------------------------------------------------|-------------------------------------------------|
| Default                                                                                  | `fastcgi_store_access user:rw;`                 |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                          |

Sets access permissions for newly created files and directories, e.g.:

```nginx
fastcgi_store_access user:rw group:rw all:r;
```

If any group or all access permissions are specified then user permissions may be omitted:

```nginx
fastcgi_store_access group:rw all:r;
```





### fastcgi_temp_file_write_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_temp_file_write_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `fastcgi_temp_file_write_size 8k|16k;`                                                                                        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                        |

Limits the size of data written to a temporary file at a time, when buffering of responses from the FastCGI server to temporary files is enabled. By default, size is limited by two buffers set by the [fastcgi_buffer_size](#fastcgi-buffer-size) and [fastcgi_buffers](#fastcgi-buffers) directives. The maximum size of a temporary file is set by the [fastcgi_max_temp_file_size](#fastcgi-max-temp-file-size) directive.





### fastcgi_temp_path

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `fastcgi_temp_path` path [level1 [level2 [level3]]]\`;                                                                                                                                |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `fastcgi_temp_path fastcgi_temp;`
(the path depends on the `--http-fastcgi-temp-path` [build parameter](https://en.angie.software//angie/docs/installation/sourcebuild.md#paths)) |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                                                                                |

Defines a directory for storing temporary files with data received from FastCGI servers. Up to three-level subdirectory hierarchy can be used under the specified directory. For example, in the following configuration

```nginx
fastcgi_temp_path /spool/angie/fastcgi_temp 1 2;
```

a temporary file might look like this:

```nginx
/spool/angie/fastcgi_temp/7/45/00000123457
```

See also the use_temp_path parameter of the [fastcgi_cache_path](#fastcgi-cache-path) directive.



## Parameters Passed to a FastCGI Server

HTTP request header fields are passed to a FastCGI server as parameters. In applications and scripts run as FastCGI servers, these parameters are usually available as environment variables. For example, the `User-Agent` header field is passed as the HTTP_USER_AGENT parameter. Besides HTTP request header fields, arbitrary parameters can be passed using the [fastcgi_param](#fastcgi-param) directive.



## Built-in Variables

The http_fastcgi module supports built-in variables that can be used to set parameters using the [fastcgi_param](#fastcgi-param) directive:



### `$fastcgi_path_info`

The value of the second capture group set by the [fastcgi_split_path_info](#fastcgi-split-path-info) directive. This variable can be used to set the PATH_INFO parameter.



### `$fastcgi_script_name`

Request URI or, if a URI ends with a slash, request URI with an index file name configured by the [fastcgi_index](#fastcgi-index) directive appended to it. This variable can be used to set the SCRIPT_FILENAME and PATH_TRANSLATED parameters that are used, in particular, to determine the script name in PHP. For example, for the `/info/` request with the following directives

```nginx
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name;
```

the SCRIPT_FILENAME parameter will be equal to `/home/www/scripts/php/info/index.php`.

When using the [fastcgi_split_path_info](#fastcgi-split-path-info) directive, the $fastcgi_script_name variable equals the value of the first capture group set by this directive.


# https://en.angie.software/angie/docs/configuration/modules/http/http_flv.md





# FLV

The module provides pseudo-streaming server-side support for Flash Video (FLV) files.

It handles requests with the start argument in the request URI's query string specially, by sending back the contents of a file starting from the requested byte offset and with the prepended FLV header.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module isn't built
by default; it must be enabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--with-http_flv_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
location ~ \.flv$ {
    flv;
}
```



## Directives





### flv

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `flv`;   |
|------------------------------------------------------------------------------------------|----------|
| Default                                                                                  | —        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | location |

Turns on module processing in a surrounding location.


# https://en.angie.software/angie/docs/configuration/modules/http/http_geo.md





# Geo

The module creates variables with values depending on the client IP address.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by
default; it can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-http_geo_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
geo $geo {
    default        0;

    127.0.0.1      2;
    192.168.1.0/24 1;
    10.1.0.0/16    1;

    ::1            2;
    2001:0db8::/32 1;
}
```



## Directives





### geo

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `geo` [$address] $variable { ... }   |
|------------------------------------------------------------------------------------------|--------------------------------------|
| Default                                                                                  | —                                    |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                                 |

Describes the dependency of values of the specified variable on the client IP address. By default, the address is taken from the [$remote_addr](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-remote-addr) variable, but it can also be taken from another variable, for example:

```nginx
geo $arg_remote_addr $geo {
    ...;
}
```

#### NOTE
Since variables are evaluated only when used, the mere existence of even a large number of declared `geo` variables does not cause any extra costs for request processing.

If the value of a variable does not represent a valid IP address then the "255.255.255.255" address is used.

Addresses are specified either as prefixes in CIDR notation (including individual addresses) or as ranges.

The following special parameters are also supported:

| `delete`          | deletes the specified network                                                                                                                                                                                                                                                                                                                                                                                |
|-------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `default`         | the value set to the variable if the client address does not match any of the specified addresses. When addresses are specified in CIDR notation, `0.0.0.0/0` and `::/0` can be used instead of `default`. When `default` is not specified, the default value will be an empty string                                                                                                                        |
| `include`         | includes a file with addresses and values. The file name can contain glob wildcards, in which case all matching files are included. There can be several inclusions.                                                                                                                                                                                                                                         |
| `proxy`           | defines trusted addresses. When a request comes from a trusted address, an address from the `X-Forwarded-For` request header field will be used instead. In contrast to the regular addresses, trusted addresses are checked sequentially.                                                                                                                                                                   |
| `proxy_recursive` | enables recursive address search. If recursive search is disabled then instead of the original client address that matches one of the trusted addresses, the last address sent in `X-Forwarded-For` will be used. If recursive search is enabled then instead of the original client address that matches one of the trusted addresses, the last non-trusted address sent in `X-Forwarded-For` will be used. |
| `ranges`          | indicates that addresses are specified as ranges. This parameter should be the first. To speed up loading of a geo base, addresses should be put in ascending order.                                                                                                                                                                                                                                         |
| `volatile`        | indicates that the variable is not cacheable.                                                                                                                                                                                                                                                                                                                                                                |

Example:

```nginx
geo $country {
    default        ZZ;
    include        conf/geo.conf;
    delete         127.0.0.0/16;
    proxy          192.168.100.0/24;
    proxy          2001:0db8::/32;

    127.0.0.0/24   US;
    127.0.0.1/32   RU;
    10.1.0.0/16    RU;
    192.168.1.0/24 UK;
}
```

The `conf/geo.conf` file could contain the following lines:

```console
10.2.0.0/16    RU;
192.168.2.0/24 RU;
```

The value of the most specific match is used. For example, for the `127.0.0.1` address, the value `RU` will be chosen, not `US`.

Sample range description:

```nginx
geo $country {
    ranges;
    default                   ZZ;
    127.0.0.0-127.0.0.0       US;
    127.0.0.1-127.0.0.1       RU;
    127.0.0.2-127.0.0.255     US;
    10.1.0.0-10.1.255.255     RU;
    192.168.1.0-192.168.1.255 UK;
}
```


# https://en.angie.software/angie/docs/configuration/modules/http/http_geoip.md





# GeoIP

Creates variables with values depending on the client IP address,
using the precompiled [MaxMind](http://www.maxmind.com/) databases
or their counterparts.

When using the databases with IPv6 support,
IPv4 addresses are looked up as IPv4-mapped IPv6 addresses.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module isn't built
by default; it must be enabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--with-http_geoip_module`.

The module isn't included in packages and images from
[our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages).

#### NOTE
This module requires the [MaxMind GeoIP](https://www.maxmind.com/en/geoip-databases) database
or a counterpart such as [MaxMind GeoLite2](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data).



## Configuration Example

```nginx
http {
    geoip_country         GeoIP.dat;
    geoip_city            GeoLiteCity.dat;
    geoip_proxy           192.168.100.0/24;
    geoip_proxy           2001:0db8::/32;
    geoip_proxy_recursive on;
    ...
```



## Directives





### geoip_city

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `geoip_city` file;   |
|------------------------------------------------------------------------------------------|----------------------|
| Default                                                                                  | —                    |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                 |

Specifies a database used to determine the country, region, and city depending on the client IP address. The following variables are available when using this database:

| `$geoip_city_continent_code`   | two-letter continent code, for example, "EU", "NA".                                                                                                                                   |
|--------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `$geoip_city_country_code`     | two-letter country code, for example, "RU", "US".                                                                                                                                     |
| `$geoip_city_country_code3`    | three-letter country code, for example, "RUS", "USA".                                                                                                                                 |
| `$geoip_city_country_name`     | country name, for example, "Russian Federation", "United States".                                                                                                                     |
| `$geoip_dma_code`              | DMA region code in US (also known as "metro code"), according to the [geotargeting](https://developers.google.com/adwords/api/docs/appendix/cities-DMAregions) in Google AdWords API. |
| `$geoip_latitude`              | latitude.                                                                                                                                                                             |
| `$geoip_longitude`             | longitude.                                                                                                                                                                            |
| `$geoip_region`                | two-symbol country region code (region, territory, state, province, federal land and the like), for example, "48", "DC".                                                              |
| `$geoip_region_name`           | country region name (region, territory, state, province, federal land and the like), for example, "Moscow City", "District of Columbia".                                              |
| `$geoip_city`                  | city name, for example, "Moscow", "Washington".                                                                                                                                       |
| `$geoip_postal_code`           | postal code.                                                                                                                                                                          |





### geoip_country

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `geoip_country` file;   |
|------------------------------------------------------------------------------------------|-------------------------|
| Default                                                                                  | —                       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                    |

Specifies a database used to determine the country depending on the client IP address. The following variables are available when using this database:

| `$geoip_country_code`   | two-letter country code, for example, "RU", "US".                 |
|-------------------------|-------------------------------------------------------------------|
| `$geoip_country_code3`  | three-letter country code, for example, "RUS", "USA".             |
| `$geoip_country_name`   | country name, for example, "Russian Federation", "United States". |





### geoip_org

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `geoip_org` file;   |
|------------------------------------------------------------------------------------------|---------------------|
| Default                                                                                  | —                   |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                |

Specifies a database used to determine the organization depending on the client IP address. The following variable is available when using this database:

| `$geoip_org`   | organization name, for example, "The University of Melbourne".   |
|----------------|------------------------------------------------------------------|





### geoip_proxy

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `geoip_proxy` address | CIDR | unix:;   |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| Default                                                                                  | —                                       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                                    |

Defines trusted addresses. When a request comes from a trusted address, an address from the `X-Forwarded-For` request header field will be used instead.





### geoip_proxy_recursive

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `geoip_proxy_recursive` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| Default                                                                                  | `geoip_proxy_recursive off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                                    |

If recursive search is disabled then instead of the original client address that matches one of the trusted addresses, the last address sent in `X-Forwarded-For` will be used. If recursive search is enabled then instead of the original client address that matches one of the trusted addresses, the last non-trusted address sent in `X-Forwarded-For` will be used.


# https://en.angie.software/angie/docs/configuration/modules/http/http_grpc.md





# gRPC

Allows passing requests to a gRPC server.

#### NOTE
This module requires the [HTTP/2](https://en.angie.software//angie/docs/configuration/modules/http/http_v2.md#http-v2) module.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by
default; it can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-http_grpc_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
server {
    listen 9000;

    http2 on;

    location / {
        grpc_pass 127.0.0.1:9000;
    }
}
```



## Directives





### grpc_bind

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `grpc_bind` address [`transparent`] | `off`;   |
|------------------------------------------------------------------------------------------|------------------------------------------------|
| Default                                                                                  | —                                              |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                         |

Makes outgoing connections to a gRPC server originate from the specified local IP address with an optional port. Parameter value can contain [variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables). The special value `off` cancels the effect of the grpc_bind directive inherited from the previous configuration level, which allows the system to auto-assign the local IP address and port.

By default, this value is evaluated once when the request is initialized, before
a gRPC server is selected. In Angie PRO, evaluation happens after each gRPC
server selection (including retries), so the bind address can depend on the
selected server; for example, via the `$upstream_current_addr` variable.
If the evaluated value is empty, no binding is made.

The `transparent` parameter allows outgoing connections to a gRPC server
originate from a non-local IP address, for example, from a real IP address of a
client:

```nginx
grpc_bind $remote_addr transparent;
```

In order for this parameter to work, it is usually necessary to run Angie worker processes with the [superuser](https://en.angie.software//angie/docs/configuration/modules/core.md#user) privileges. On Linux it is not required as if the `transparent` parameter is specified, worker processes inherit the CAP_NET_RAW capability from the master process.

#### NOTE
It is necessary to configure kernel routing table to intercept network traffic from the gRPC server.





### grpc_buffer_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `grpc_buffer_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `grpc_buffer_size 4k|8k;`                                                                                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                            |

Sets the size of the buffer used for reading the first part of the response received from the gRPC server. The response is passed to the client synchronously, as soon as it is received.





### grpc_connect_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `grpc_connect_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `grpc_connect_timeout 60s;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                |

Defines a timeout for establishing a connection with a gRPC server. It should be noted that this timeout cannot usually exceed 75 seconds.

#### NOTE
This timeout does not govern idle connections: how long an already-open one
is kept for reuse is set by [keepalive_timeout](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive-timeout) in an upstream block
whose connections are cached with [keepalive](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive).





### grpc_connection_drop

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `grpc_connection_drop` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units) | `on` | `off`;   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `grpc_connection_drop off;`                                                                                                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                               |

Enables termination of all active connections to the proxied server after it has been
removed from the group or marked as permanently unavailable by a [reresolve](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve) process or the [API command](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-config-methods)
`DELETE`.
Idle connections in the [cache](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive) are not affected.

A connection is terminated when the next read or write event is processed for
either the client or the proxied server.

Setting time enables a connection termination [timeout](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);
with `on` set, connections are dropped immediately.





### grpc_hide_header

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `grpc_hide_header` field;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| Default                                                                                  | —                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location      |

By default, Angie does not pass the header fields `Date`, `Server`, and `X-Accel-...` from the response of a gRPC server to a client. The `grpc_hide_header` directive sets additional fields that will not be passed. If, on the contrary, the passing of fields needs to be permitted, the [grpc_pass_header](#grpc-pass-header) directive can be used.





### grpc_ignore_headers

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `grpc_ignore_headers` field ...;   |
|------------------------------------------------------------------------------------------|------------------------------------|
| Default                                                                                  | —                                  |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location             |

Disables processing of certain response header fields from the gRPC server. The following fields can be ignored: `X-Accel-Redirect` and `X-Accel-Charset`.

If not disabled, processing of these header fields has the following effect:

* `X-Accel-Redirect` performs an [internal redirect](https://en.angie.software//angie/docs/configuration/modules/http/index.md#internal) to the specified URI;
* `X-Accel-Charset` sets the desired [charset](https://en.angie.software//angie/docs/configuration/modules/http/http_charset.md#id1) of a response.





### grpc_intercept_errors

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `grpc_intercept_errors` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| Default                                                                                  | `grpc_intercept_errors off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                  |

Determines whether gRPC server responses with codes greater than or equal to 300 should be passed to a client or be intercepted and redirected to Angie for processing with the [error_page](https://en.angie.software//angie/docs/configuration/modules/http/index.md#error-page) directive.





### grpc_next_upstream

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `grpc_next_upstream` `error` | `timeout` | `invalid_header` | `http_500` | `http_502` | `http_503` | `http_504` | `http_403` | `http_404` | `http_429` | `non_idempotent` | `off` ...;   |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `grpc_next_upstream error timeout;`                                                                                                                                                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                                                                                   |

Specifies in which cases a request should be passed to the next server in the [upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream) group:

| `error`          | an error occurred while establishing a connection with the server, passing a request to it, or reading the response header;                                                                                                                                                                             |
|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `timeout`        | a timeout has occurred while establishing a connection with the server, passing a request to it, or reading the response header;                                                                                                                                                                        |
| `invalid_header` | a server returned an empty or invalid response;                                                                                                                                                                                                                                                         |
| `http_500`       | a server returned a response with the code 500;                                                                                                                                                                                                                                                         |
| `http_502`       | a server returned a response with the code 502;                                                                                                                                                                                                                                                         |
| `http_503`       | a server returned a response with the code 503;                                                                                                                                                                                                                                                         |
| `http_504`       | a server returned a response with the code 504;                                                                                                                                                                                                                                                         |
| `http_403`       | a server returned a response with the code 403;                                                                                                                                                                                                                                                         |
| `http_404`       | a server returned a response with the code 404;                                                                                                                                                                                                                                                         |
| `http_429`       | a server returned a response with the code 429;                                                                                                                                                                                                                                                         |
| `non_idempotent` | normally, requests with a [non-idempotent](https://datatracker.ietf.org/doc/html/rfc7231#section-4.2.2) method
(`POST`, `LOCK`, `PATCH`) are not passed to the next
server if a request has been sent to an upstream server; enabling this
option explicitly allows retrying such requests; |
| `off`            | disables passing a request to the next server.                                                                                                                                                                                                                                                          |

#### NOTE
One should bear in mind that passing a request to the next server is only possible if nothing has been sent to a client yet. That is, if an error or timeout occurs in the middle of the transferring of a response, fixing this is impossible.

The directive also defines what is considered an [unsuccessful attempt](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) of communication with a server.

| `error`, `timeout`, `invalid_header`                       | always considered unsuccessful attempts, even if they are not specified in the directive   |
|------------------------------------------------------------|--------------------------------------------------------------------------------------------|
| `http_500`, `http_502`, `http_503`, `http_504`, `http_429` | considered unsuccessful attempts only if they are specified in the directive               |
| `http_403`, `http_404`                                     | never considered unsuccessful attempts                                                     |

Passing a request to the next server can be limited by the [number of tries](#grpc-next-upstream-tries) and by [time](#grpc-next-upstream-timeout).





### grpc_next_upstream_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `grpc_next_upstream_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `grpc_next_upstream_timeout 0;`                                                                                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                      |

Limits the time during which a request can be passed to the [next server](#grpc-next-upstream).

| `0`   | turns off this limitation   |
|-------|-----------------------------|





### grpc_next_upstream_tries

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `grpc_next_upstream_tries` number;   |
|------------------------------------------------------------------------------------------|--------------------------------------|
| Default                                                                                  | `grpc_next_upstream_tries 0;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location               |

Limits the number of possible tries for passing a request to the [next](#grpc-next-upstream) server.

| `0`   | turns off this limitation   |
|-------|-----------------------------|





### grpc_pass

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `grpc_pass` address;     |
|------------------------------------------------------------------------------------------|--------------------------|
| Default                                                                                  | —                        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | location, if in location |

Sets the gRPC server address. The address can be specified as a domain name or IP address, and a port:

```nginx
grpc_pass localhost:9000;
```

or as a UNIX domain socket path:

```nginx
grpc_pass unix:/tmp/grpc.socket;
```

Alternatively, the `grpc://` scheme can be used:

```nginx
grpc_pass grpc://127.0.0.1:9000;
```

To use gRPC over SSL, the `grpcs://` scheme should be used:

```nginx
grpc_pass grpcs://127.0.0.1:443;
```

If a domain name resolves to several addresses, all of them will be used in a round-robin fashion. In addition, an address can be specified as a [server group](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream).

Parameter value can contain variables. In this case, if an address is specified as a domain name, the name is searched among the described server groups, and, if not found, is determined using a [resolver](https://en.angie.software//angie/docs/configuration/modules/http/index.md#resolver).

#### NOTE
If `grpc_pass` is specified in a `location` with a trailing slash in the prefix
(for example, `location /name/`),
and the [auto_redirect](https://en.angie.software//angie/docs/configuration/modules/http/index.md#auto-redirect) directive is set to `default`,
requests without a trailing slash will be redirected (`/name -> /name/`).





### grpc_pass_header

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `grpc_pass_header` field;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| Default                                                                                  | —                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location      |

Permits passing [otherwise disabled](#grpc-hide-header) header fields from a gRPC server to a client.





### grpc_read_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `grpc_read_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `grpc_read_timeout 60s;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                             |

Defines a timeout for reading a response from the gRPC server. The timeout is set only between two successive read operations, not for the transmission of the whole response. If the gRPC server does not transmit anything within this time, the connection is closed.





### grpc_send_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `grpc_send_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `grpc_send_timeout 60s;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                             |

Sets a timeout for transmitting a request to the gRPC server. The timeout is set only between two successive write operations, not for the transmission of the whole request. If the gRPC server does not receive anything within this time, the connection is closed.





### grpc_set_header

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `grpc_set_header` field value;                    |
|------------------------------------------------------------------------------------------|---------------------------------------------------|
| Default                                                                                  | `grpc_set_header Content-Length $content_length;` |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                            |

Allows redefining or appending fields to the request header [passed](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass-request-headers) to the gRPC server. The value can contain variables. These directives are inherited from the previous configuration level if and only if there are no grpc_set_header directives defined on the current level.

If the value of a header field is an empty string then this field will not be passed to the gRPC server:

```nginx
grpc_set_header Accept-Encoding "";
```





### grpc_socket_keepalive

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `grpc_socket_keepalive` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| Default                                                                                  | `grpc_socket_keepalive off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                  |

Configures the "TCP keepalive" behavior for outgoing connections to a gRPC server.

| `off`   | By default, the operating system's settings are in effect for the socket.   |
|---------|-----------------------------------------------------------------------------|
| `on`    | The SO_KEEPALIVE socket option is turned on for the socket.                 |





### grpc_ssl_certificate

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `grpc_ssl_certificate` file;   |
|------------------------------------------------------------------------------------------|--------------------------------|
| Default                                                                                  | —                              |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location         |

Specifies a file with the certificate in the PEM format used for authentication to a gRPC SSL server. The file name can contain variables.





### grpc_ssl_certificate_cache

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `grpc_ssl_certificate_cache` `off`;

`grpc_ssl_certificate_cache` `max=`N [`inactive=`time] [`valid=`time];   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `grpc_ssl_certificate_cache off;`                                                                                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                |

Defines a cache that stores [SSL certificates](#grpc-ssl-certificate) and [secret keys](#grpc-ssl-certificate-key) specified using variables.

The directive supports the following parameters:

- `max` — sets the maximum number of elements in the cache. When the cache
  overflows, the least recently used (LRU) elements are removed.
- `inactive` — defines the time after which an element is removed if it
  has not been accessed during this time, even if still within its
  `valid` period; each access resets this timer. The default is 10
  seconds.
- `valid` — defines the time during which a cached element is considered
  valid and can be reused. The default is 60 seconds. After this period,
  certificates are reloaded or revalidated.
- `off` — disables the cache.

Example:

```nginx
grpc_ssl_certificate       $grpc_ssl_server_name.crt;
grpc_ssl_certificate_key   $grpc_ssl_server_name.key;
grpc_ssl_certificate_cache max=1000 inactive=20s valid=1m;
```





### grpc_ssl_certificate_key

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `grpc_ssl_certificate_key` file;   |
|------------------------------------------------------------------------------------------|------------------------------------|
| Default                                                                                  | —                                  |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location             |

Specifies a file with the secret key in the PEM format used for authentication to a gRPC SSL server.

The value `engine:`name`:id` can be specified instead of the file, which loads a secret key with a specified id from the OpenSSL engine name.

The value `store:scheme:id` can be specified instead of the file, which is used to load a secret key with a specified id and OpenSSL provider registered URI scheme, such as [pkcs11](https://datatracker.ietf.org/doc/html/rfc7512).

The file name can contain variables.





### grpc_ssl_ciphers

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `grpc_ssl_ciphers` ciphers;   |
|------------------------------------------------------------------------------------------|-------------------------------|
| Default                                                                                  | `grpc_ssl_ciphers DEFAULT;`   |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location        |

Specifies the enabled ciphers for requests to a gRPC SSL server. The ciphers are specified in the format understood by the OpenSSL library.

The list of ciphers depends on the version of OpenSSL installed.
The full list can be viewed using the `openssl ciphers` command.

#### WARNING
The `grpc_ssl_ciphers` directive does *not* configure ciphers for TLS
1.3 when using OpenSSL. To tune TLS 1.3 ciphers with OpenSSL, use the
[grpc_ssl_conf_command](#grpc-ssl-conf-command) directive, which was added to support advanced
SSL configuration.

- In LibreSSL, TLS 1.3 ciphers *can* be configured using
  `grpc_ssl_ciphers`.
- In BoringSSL, TLS 1.3 ciphers cannot be configured at all.





### grpc_ssl_conf_command

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `grpc_ssl_conf_command` name value;   |
|------------------------------------------------------------------------------------------|---------------------------------------|
| Default                                                                                  | —                                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                |

Sets arbitrary OpenSSL configuration [commands](https://docs.openssl.org/master/man3/SSL_CONF_cmd/) when establishing a connection with the gRPC SSL server.

#### NOTE
The directive is supported when using OpenSSL 1.0.2 or higher.
To configure TLS 1.3 ciphers with OpenSSL, use the `ciphersuites` command.

Several grpc_ssl_conf_command directives can be specified on the same level. These directives are inherited from the previous configuration level if and only if there are no grpc_ssl_conf_command directives defined on the current level.

#### WARNING
Note that configuring OpenSSL directly might result in unexpected behavior.





### grpc_ssl_crl

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `grpc_ssl_crl` file;   |
|------------------------------------------------------------------------------------------|------------------------|
| Default                                                                                  | —                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location |

Specifies a file with revoked certificates (CRL) in the PEM format used to [verify](#grpc-ssl-verify) the certificate of the gRPC SSL server.





### grpc_ssl_name

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `grpc_ssl_name` name;                        |
|------------------------------------------------------------------------------------------|----------------------------------------------|
| Default                                                                                  | `grpc_ssl_name `host name` from grpc_pass;\` |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                       |

Allows overriding the server name used to [verify](#grpc-ssl-verify) the certificate of the gRPC SSL server and to be [passed through SNI](#grpc-ssl-server-name) when establishing a connection with the gRPC SSL server.

The server name can also be specified with variables.

By default, the host name from [grpc_pass](#grpc-pass) is used.





### grpc_ssl_password_file

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `grpc_ssl_password_file` file;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | —                                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location           |

Specifies a file with passphrases for [secret keys](#grpc-ssl-certificate-key) where each passphrase is specified on a separate line. Passphrases are tried in turn when loading the key.





### grpc_ssl_protocols

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `grpc_ssl_protocols` [`SSLv2`] [`SSLv3`] [`TLSv1`] [`TLSv1.1`] [`TLSv1.2`] [`TLSv1.3`];   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| Default                                                                                  | `grpc_ssl_protocols TLSv1.2 TLSv1.3;`                                                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                    |

Enables the specified protocols for requests to a gRPC SSL server.





### grpc_ssl_server_name

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `grpc_ssl_server_name` `on` | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------------------|
| Default                                                                                  | `grpc_ssl_server_name off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                 |

Enables or disables passing the server name
set by the [grpc_ssl_name](#grpc-ssl-name) directive
via the
[Server Name Indication](http://en.wikipedia.org/wiki/Server_Name_Indication)
TLS extension
(SNI,
[RFC 6066](https://datatracker.ietf.org/doc/html/rfc6066.html))
while establishing a connection with the gRPC SSL server.





### grpc_ssl_session_reuse

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `grpc_ssl_session_reuse` `on` | `off`;   |
|------------------------------------------------------------------------------------------|------------------------------------------|
| Default                                                                                  | `grpc_ssl_session_reuse on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                   |

Determines whether SSL sessions can be reused when working with the gRPC server. If the errors "SSL3_GET_FINISHED:digest check failed" appear in the logs, try disabling session reuse.





### grpc_ssl_trusted_certificate

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `grpc_ssl_trusted_certificate` file;   |
|------------------------------------------------------------------------------------------|----------------------------------------|
| Default                                                                                  | —                                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                 |

Specifies a file with trusted CA certificates in the PEM format used to [verify](#grpc-ssl-verify) the certificate of the gRPC SSL server.





### grpc_ssl_verify

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `grpc_ssl_verify` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-----------------------------------|
| Default                                                                                  | `grpc_ssl_verify off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location            |

Enables or disables verification of the gRPC SSL server certificate.





### grpc_ssl_verify_depth

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `grpc_ssl_verify_depth` number;   |
|------------------------------------------------------------------------------------------|-----------------------------------|
| Default                                                                                  | `grpc_ssl_verify_depth 1;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location            |

Sets the verification depth in the gRPC SSL server certificates chain.


# https://en.angie.software/angie/docs/configuration/modules/http/http_gunzip.md





# GunZIP

The module is a filter that decompresses responses with `Content-Encoding: gzip` for clients that do not support "gzip" encoding method. The module will be useful when it is desirable to store data compressed to save space and reduce I/O costs.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module isn't built
by default; it must be enabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--with-http_gunzip_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
location /storage/ {
    gunzip on;
#    ...
}
```



## Directives





### gunzip

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `gunzip` `on` | `off`;   |
|------------------------------------------------------------------------------------------|--------------------------|
| Default                                                                                  | `gunzip off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location   |

Enables or disables decompression of gzipped responses for clients that lack gzip support. If enabled, the following directives are also taken into account when determining if clients support gzip: [gzip_http_version](https://en.angie.software//angie/docs/configuration/modules/http/http_gzip.md#gzip-http-version), [gzip_proxied](https://en.angie.software//angie/docs/configuration/modules/http/http_gzip.md#gzip-proxied) and [gzip_disable](https://en.angie.software//angie/docs/configuration/modules/http/http_gzip.md#gzip-disable). See also the [gzip_vary](https://en.angie.software//angie/docs/configuration/modules/http/http_gzip.md#gzip-vary) directive.





### gunzip_buffers

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `gunzip_buffers` number [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `gunzip_buffers 32 4k | 16 8k;`                                                                                        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                 |

Sets the number and size of buffers used to decompress a response. By default, the buffer size is equal to one memory page. This is either 4K or 8K, depending on a platform.


# https://en.angie.software/angie/docs/configuration/modules/http/http_gzip.md





# GZip

A filter that compresses responses using the gzip method, which allows reducing the size of transmitted data by 2 times or more.

#### WARNING
When using the SSL/TLS protocol, compressed responses may be subject to [BREACH](https://en.wikipedia.org/wiki/BREACH) attacks.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by
default; it can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-http_gzip_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
gzip            on;
gzip_min_length 1000;
gzip_proxied    expired no-cache no-store private auth;
gzip_types      text/plain application/xml;
```

The [$gzip_ratio](#v-gzip-ratio) variable can be used to log the achieved compression ratio.



## Directives





### gzip

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `gzip` `on` | `off`;                   |
|------------------------------------------------------------------------------------------|----------------------------------------|
| Default                                                                                  | `gzip off;`                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location, if in location |

Enables or disables gzipping of responses.





### gzip_buffers

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `gzip_buffers` number [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `gzip_buffers 32 4k | 16 8k;`                                                                                        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                               |

Sets the number and size of buffers used to compress a response. By default, the buffer size is equal to one memory page. This is either 4K or 8K, depending on a platform.





### gzip_comp_level

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `gzip_comp_level` level;   |
|------------------------------------------------------------------------------------------|----------------------------|
| Default                                                                                  | `gzip_comp_level 1;`       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location     |

Sets a gzip compression level of a response. Acceptable values are in the range from 1 to 9.





### gzip_disable

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `gzip_disable` regex ...;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| Default                                                                                  | —                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location      |

Disables gzipping of responses for requests with `User-Agent` header fields matching any of the specified regular expressions.

The special mask `msie6` corresponds to the regular expression "MSIE [4-6].", but works faster. "MSIE 6.0; ... SV1" is excluded from this mask.





### gzip_http_version

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `gzip_http_version` `1.0` | `1.1`;   |
|------------------------------------------------------------------------------------------|--------------------------------------|
| Default                                                                                  | `gzip_http_version 1.1;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location               |

Sets the minimum HTTP version of a request required to compress a response.





### gzip_min_length

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `gzip_min_length` length;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| Default                                                                                  | `gzip_min_length 20;`       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location      |

Sets the minimum length of a response that will be gzipped. The length is determined only from the `Content-Length` response header field.





### gzip_proxied

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `gzip_proxied` `off` | `expired` | `no-cache` | `no-store` | `private` | `no_last_modified` | `no_etag` | `auth` | `any` ...;   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `gzip_proxied off;`                                                                                                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                          |

Enables or disables gzipping of responses for proxied requests depending on the request and response. The fact that the request is proxied is determined by the presence of the `Via` request header field. The directive accepts multiple parameters:

| `off`              | disables compression for all proxied requests, ignoring other parameters;                                  |
|--------------------|------------------------------------------------------------------------------------------------------------|
| `expired`          | enables compression if a response header includes the `Expires` field with a value that disables caching;  |
| `no-cache`         | enables compression if a response header includes the `Cache-Control` field with the "no-cache" parameter; |
| `no-store`         | enables compression if a response header includes the `Cache-Control` field with the "no-store" parameter; |
| `private`          | enables compression if a response header includes the `Cache-Control` field with the "private" parameter;  |
| `no_last_modified` | enables compression if a response header does not include the `Last-Modified` field;                       |
| `no_etag`          | enables compression if a response header does not include the `ETag` field;                                |
| `auth`             | enables compression if a request header includes the `Authorization` field;                                |
| `any`              | enables compression for all proxied requests.                                                              |





### gzip_types

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `gzip_types` mime-type ...;   |
|------------------------------------------------------------------------------------------|-------------------------------|
| Default                                                                                  | `gzip_types text/html;`       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location        |

Enables gzipping of responses for the specified MIME types in addition to `text/html`. The special value "\*" matches any MIME type. Responses with the `text/html` type are always compressed.





### gzip_vary

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `gzip_vary` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| Default                                                                                  | `gzip_vary off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location      |

Enables or disables inserting the "Vary: Accept-Encoding" response header field if the directives [gzip](#id1), [gzip_static](https://en.angie.software//angie/docs/configuration/modules/http/http_gzip_static.md#id1) or [gunzip](https://en.angie.software//angie/docs/configuration/modules/http/http_gunzip.md#id1) are active.



## Built-in Variables



### `$gzip_ratio`

achieved compression ratio, computed as the ratio between the original and compressed response sizes.


# https://en.angie.software/angie/docs/configuration/modules/http/http_gzip_static.md





# GZip Static

Allows sending precompressed files with the ".gz" filename extension instead of regular files.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module isn't built
by default; it must be enabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--with-http_gzip_static_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
gzip_static  on;
gzip_proxied expired no-cache no-store private auth;
```



## Directives





### gzip_static

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `gzip_static` `on` | `off` | `always`;   |
|------------------------------------------------------------------------------------------|------------------------------------------|
| Default                                                                                  | `gzip_static off;`                       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                   |

Enables (`on`) or disables (`off`) checking the existence of precompressed files. The following directives are also taken into account: [gzip_http_version](https://en.angie.software//angie/docs/configuration/modules/http/http_gzip.md#gzip-http-version), [gzip_proxied](https://en.angie.software//angie/docs/configuration/modules/http/http_gzip.md#gzip-proxied), [gzip_disable](https://en.angie.software//angie/docs/configuration/modules/http/http_gzip.md#gzip-disable) and [gzip_vary](https://en.angie.software//angie/docs/configuration/modules/http/http_gzip.md#gzip-vary).

With `always`, gzipped files are used in all cases, without checking if the client supports it. This is useful if there are no uncompressed files on the disk anyway or the [GunZIP](https://en.angie.software//angie/docs/configuration/modules/http/http_gunzip.md#http-gunzip) module is used.

The files can be compressed using the gzip command, or any other compatible one. It is recommended that the modification date and time of original and compressed files be the same.


# https://en.angie.software/angie/docs/configuration/modules/http/http_headers.md





# Headers

Allows adding the `Expires` and `Cache-Control` header fields, and arbitrary fields, to a response header.



## Configuration Example

```nginx
expires    24h;
expires    modified +24h;
expires    @24h;
expires    0;
expires    -1;
expires    epoch;
expires    $expires;
add_header Cache-Control private;
```



## Directives





### add_header

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `add_header` name value [`always`];    |
|------------------------------------------------------------------------------------------|----------------------------------------|
| Default                                                                                  | —                                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location, if in location |

Adds the specified field to a response header provided that the response code equals 200, 201 (1.3.10), 204, 206, 301, 302, 303, 304, 307, or 308. Parameter value can contain [variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables).

There could be several `add_header` directives. These directives are inherited from the previous configuration level if and only if there are no `add_header` directives defined on the current level.

If the `always` parameter is specified, the header field will be added regardless of the response code.





### add_trailer

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `add_trailer` name value [`always`];   |
|------------------------------------------------------------------------------------------|----------------------------------------|
| Default                                                                                  | —                                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location, if in location |

Adds the specified field to the end of a response provided that the response code equals 200, 201, 206, 301, 302, 303, 307, or 308. Parameter value can contain variables.

There could be several `add_trailer` directives. These directives are inherited from the previous configuration level if and only if there are no `add_trailer` directives defined on the current level.

If the `always` parameter is specified, the specified field will be added regardless of the response code.





### expires

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `expires` [`modified`] [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);

`expires` `epoch` | `max` | `off`;   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `expires off;`                                                                                                                                                    |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location, if in location                                                                                                                            |

Enables or disables adding or modifying the `Expires` and `Cache-Control` response header fields provided that the response code equals 200, 201, 204, 206, 301, 302, 303, 304, 307, or 308. The parameter can be a positive or negative [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units).

The time in the `Expires` field is computed as a sum of the current time and time specified in the directive. If the `modified` parameter is used, then the time is computed as a sum of the file's modification time and the time specified in the directive.

In addition, it is possible to specify a time of day using the "@" prefix:

```nginx
expires @15h30m;
```

The contents of the `Cache-Control` field depends on the sign of the specified time:

* time is negative — "Cache-Control: no-cache".
* time is positive or zero — "Cache-Control: max-age=\`t\`", where t is a time specified in the directive, in seconds.

| `epoch`   | sets `Expires` to the value "Thu, 01 Jan 1970 00:00:01 GMT", and `Cache-Control` to "no-cache".   |
|-----------|---------------------------------------------------------------------------------------------------|
| `max`     | sets `Expires` to the value "Thu, 31 Dec 2037 23:55:55 GMT", and `Cache-Control` to 10 years.     |
| `off`     | disables adding or modifying the `Expires` and `Cache-Control` response header fields.            |

The last parameter value can contain variables:

```nginx
map $sent_http_content_type $expires {
    default         off;
    application/pdf 42d;
    ~image/         max;
}

expires $expires;
```


# https://en.angie.software/angie/docs/configuration/modules/http/http_image_filter.md





# Image Filter

The module is a filter that transforms images in JPEG, GIF, PNG, WebP, HEIC,
and AVIF formats.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module isn't built
by default; it must be enabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--with-http_image_filter_module`.

In [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the module is built
[dynamically](https://en.angie.software//angie/docs/installation/index.md#install-dynamicmodules) and is available as a separate
package named `angie-module-image-filter` or
`angie-pro-module-image-filter`.

In our repositories, the module is built
[dynamically](https://en.angie.software//angie/docs/installation/index.md#install-dynamicmodules)
and is available as a separate package named
`angie-module-image-filter` or `angie-pro-module-image-filter`.

#### NOTE
This module utilizes the [libgd](http://libgd.org/) library. It is recommended to use the latest available version of the library.

To transform images in WebP, HEIC, or AVIF formats, the `libgd` library
must be compiled with support for these formats.



## Configuration Example

```nginx
location /img/ {
    proxy_pass   http://backend;
    image_filter resize 150 100;
    image_filter rotate 90;
    error_page   415 = /empty;
}

location = /empty {
    empty_gif;
}
```



## Directives





### image_filter

#### Versionchanged
Changed in version 1.11.0.

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | - `image_filter` `off`;
- `image_filter` `test`;
- `image_filter` `size`;
- `image_filter` rotate `90` | `180` | `270`;
- `image_filter` resize width height;
- `image_filter` crop width height;
- `image_filter` convert type;   |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `image_filter off;`                                                                                                                                                                                                                                        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | location                                                                                                                                                                                                                                                   |

Sets the type of transformation to perform on images:

| `off`                 | turns off module processing in a surrounding location.                                                                                                                                                                                                                                                                                                                                         |
|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `test`                | ensures that responses are images in JPEG, GIF, PNG, WebP, HEIC, or AVIF
format. Otherwise, the 415 (Unsupported Media Type) error is returned.                                                                                                                                                                                                                                            |
| `size`                | outputs information about images in a JSON format, e.g.:
` *"img" : { "width": 100, "height": 100, "type": "gif"*  }`
In case of an error, the output is as follows: `{}`                                                                                                                                                                                                              |
| `rotate 90|180|270`   | rotates images counter-clockwise by the specified number of degrees.
Parameter value can contain [variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables). This mode can be used either alone
or along with the `resize` and `crop` transformations.                                                                                            |
| `resize` width height | proportionally reduces an image to the specified sizes. To reduce by only one dimension, another dimension can be specified as "-". In case of an error, the server will return code 415 (Unsupported Media Type). Parameter values can contain variables. When used along with the `rotate` parameter, the rotation happens **after** reduction.                                              |
| `crop` width height   | proportionally reduces an image to the larger side size and crops extraneous edges by another side. To reduce by only one dimension, another dimension can be specified as "-". In case of an error, the server will return code 415 (Unsupported Media Type). Parameter values can contain variables. When used along with the `rotate` parameter, the rotation happens **before** reduction. |
| `convert` type        | converts an image to the specified output format. Valid values are
`jpeg`, `gif`, `png`, `webp`, `heic`,
and `avif`. The parameter value can contain variables.                                                                                                                                                                                                                        |





### image_filter_avif_quality

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `image_filter_avif_quality` quality [speed];   |
|------------------------------------------------------------------------------------------|------------------------------------------------|
| Default                                                                                  | `image_filter_avif_quality 80 6;`              |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                         |

Sets the desired quality of the transformed AVIF images. The optional
`speed` parameter controls the encoder speed; both values must be
positive numbers. Parameter values can contain variables.





### image_filter_buffer

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `image_filter_buffer` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `image_filter_buffer 1M;`                                                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                               |

Sets the maximum size of the buffer used for reading images. When the size is exceeded the server returns error 415 (Unsupported Media Type).





### image_filter_heic_quality

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `image_filter_heic_quality` quality;   |
|------------------------------------------------------------------------------------------|----------------------------------------|
| Default                                                                                  | `image_filter_heic_quality 80;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                 |

Sets the desired quality of the transformed HEIC images. Acceptable values are
positive numbers. Parameter value can contain variables.





### image_filter_interlace

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `image_filter_interlace` `on` | `off`;   |
|------------------------------------------------------------------------------------------|------------------------------------------|
| Default                                                                                  | `image_filter_interlace off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                   |

If enabled, final images will be interlaced. For JPEG, final images will be in "progressive JPEG" format.





### image_filter_jpeg_quality

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `image_filter_jpeg_quality` quality;   |
|------------------------------------------------------------------------------------------|----------------------------------------|
| Default                                                                                  | `image_filter_jpeg_quality 75;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                 |

Sets the desired quality of the transformed JPEG images. Acceptable values are in the range from 1 to 100. Lesser values usually imply both lower image quality and less data to transfer. The maximum recommended value is 95. Parameter value can contain variables.





### image_filter_sharpen

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `image_filter_sharpen` percent;   |
|------------------------------------------------------------------------------------------|-----------------------------------|
| Default                                                                                  | `image_filter_sharpen 0;`         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location            |

Increases sharpness of the final image. The sharpness percentage can exceed 100. The `0` value disables sharpening. Parameter value can contain variables.





### image_filter_transparency

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `image_filter_transparency` `on` | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| Default                                                                                  | `image_filter_transparency on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                      |

Defines whether transparency should be preserved when transforming GIF images or PNG images with colors specified by a palette. The loss of transparency results in images of a better quality. The alpha channel transparency in PNG is always preserved.





### image_filter_webp_quality

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `image_filter_webp_quality` quality;   |
|------------------------------------------------------------------------------------------|----------------------------------------|
| Default                                                                                  | `image_filter_webp_quality 80;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                 |

Sets the desired quality of the transformed WebP images. Acceptable values are in the range from 1 to 100. Lesser values usually imply both lower image quality and less data to transfer. Parameter value can contain variables.


# https://en.angie.software/angie/docs/configuration/modules/http/http_index.md





# Index

The module processes requests ending with the slash character (`/`). Such requests can also be processed by the [AutoIndex](https://en.angie.software//angie/docs/configuration/modules/http/http_autoindex.md#http-autoindex) and [Random Index](https://en.angie.software//angie/docs/configuration/modules/http/http_random_index.md#http-random-index) modules.



## Configuration Example

```nginx
location / {
    index index.$geo.html index.html;
}
```



## Directives





### index

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `index` file ...;      |
|------------------------------------------------------------------------------------------|------------------------|
| Default                                                                                  | `index index.html;`    |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location |

Defines files that will be used as an index. The file name can contain [variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables). Files are checked in the specified order. The last element of the list can be a file with an absolute path. Example:

```nginx
index index.$geo.html index.0.html /index.html;
```

It should be noted that using an index file causes an internal redirect, and the request can be processed in a different location. For example, with the following configuration:

```nginx
location = / {
    index index.html;
}

location / {
#    ...
}
```

A `"/"` request will actually be processed in the second location as `"/index.html"`.


# https://en.angie.software/angie/docs/configuration/modules/http/http_limit_conn.md





# Limit Conn

The module is used to limit the number of connections per the defined key, in particular, the number of connections from a single IP address.

Not all connections are counted. A connection is counted only if it has a request being processed by the server and the whole request header has already been read.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by
default; it can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-http_limit_conn_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
http {
    limit_conn_zone $binary_remote_addr zone=addr:10m;

    ...

    server {

        ...

        location /download/ {
            limit_conn addr 1;
        }
```



## Directives





### limit_conn

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `limit_conn` zone number;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| Default                                                                                  | —                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location      |

Sets the shared memory zone and the maximum allowed number of connections for a given key value. When this limit is exceeded, the server will return the [error](#limit-conn-status) in reply to a request. For example, the directives

```nginx
limit_conn_zone $binary_remote_addr zone=addr:10m;

server {
    location /download/ {
        limit_conn addr 1;
    }
```

allow only one connection per IP address at a time.

#### NOTE
In HTTP/2 and HTTP/3, each concurrent request is considered a separate connection.

There could be several `limit_conn` directives. For example, the following configuration will limit the number of connections to the server per client IP and, at the same time, the total number of connections to the virtual server:

```nginx
limit_conn_zone $binary_remote_addr zone=perip:10m;
limit_conn_zone $server_name zone=perserver:10m;

server {
    ...
    limit_conn perip 10;
    limit_conn perserver 100;
}
```

These directives are inherited from the previous configuration level if and only if there are no `limit_conn` directives defined on the current level.





### limit_conn_dry_run

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `limit_conn_dry_run` `on` | `off`;   |
|------------------------------------------------------------------------------------------|--------------------------------------|
| Default                                                                                  | `limit_conn_dry_run off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location               |

Enables the dry run mode. In this mode, the number of connections is not limited, however, in the [shared memory zone](#limit-conn-zone), the number of excessive connections is accounted as usual.





### limit_conn_log_level

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `limit_conn_log_level` `info` | `notice` | `warn` | `error`;   |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------|
| Default                                                                                  | `limit_conn_log_level error;`                                  |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                         |

Sets the desired logging level for cases when the server limits the number of connections.





### limit_conn_status

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `limit_conn_status` code;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| Default                                                                                  | `limit_conn_status 503;`    |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location      |

Sets the status code to return in response to rejected requests.





### limit_conn_zone

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `limit_conn_zone` key zone = name:size;   |
|------------------------------------------------------------------------------------------|-------------------------------------------|
| Default                                                                                  | —                                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                                      |

Sets parameters for a shared memory zone that will keep states for various keys. In particular, the state includes the current number of connections. The key can contain [variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables). Requests with an empty key value are not accounted.

Usage example:

```nginx
limit_conn_zone $binary_remote_addr zone=addr:10m;
```

Here, a client IP address serves as a key. Note that instead of `$remote_addr`, the `$binary_remote_addr` variable is used here.

The `$remote_addr` variable's size can vary from 7 to 15 bytes. The stored state occupies either 32 or 64 bytes of memory on 32-bit platforms and always 64 bytes on 64-bit platforms.

The `$binary_remote_addr` variable's size is always 4 bytes for IPv4 addresses or 16 bytes for IPv6 addresses. The stored state always occupies 32 or 64 bytes on 32-bit platforms and 64 bytes on 64-bit platforms.

One megabyte zone can keep about 32 thousand 32-byte states or about 16 thousand 64-byte states. If the zone storage is exhausted, the server will return the [error](#limit-conn-status) to all further requests.



## Built-in Variables



### `$limit_conn_status`

keeps the result of limiting the number of connections: `PASSED`, `REJECTED`, or `REJECTED_DRY_RUN`


# https://en.angie.software/angie/docs/configuration/modules/http/http_limit_req.md






# Limit Req

The module is used to limit the request processing rate per a defined key, in particular, the processing rate of requests coming from a single IP address. The limitation is done using the "leaky bucket" method.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by
default; it can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-http_limit_req_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
http {
    limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;

    ...

    server {

        ...

        location /search/ {
            limit_req zone=one burst=5;
        }
```



## Directives





### limit_req

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `limit_req` `zone=`name [`burst=`number] [nodelay | `delay=`number];   |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------|
| Default                                                                                  | —                                                                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                 |

Sets the shared memory zone and the maximum burst size of requests. If the requests rate exceeds the rate configured for a zone, their processing is delayed such that requests are processed at a defined rate. Excessive requests are delayed until their number exceeds the maximum burst size in which case the request is terminated with an [error](#limit-req-status). By default, the maximum burst size is equal to zero. For example, the directives

```nginx
limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;

server {
    location /search/ {
        limit_req zone=one burst=5;
    }
```

allow not more than 1 request per second at an average, with bursts not exceeding 5 requests.

If delaying of excessive requests while requests are being limited is not desired, the parameter `nodelay` should be used:

```nginx
limit_req zone=one burst=5 nodelay;
```

The `delay` parameter specifies a limit at which excessive requests become delayed. Default value is zero, i.e. all excessive requests are delayed.

There could be several `limit_req` directives. For example, the following configuration will limit the processing rate of requests coming from a single IP address and, at the same time, the request processing rate by the virtual server:

```nginx
limit_req_zone $binary_remote_addr zone=perip:10m rate=1r/s;
limit_req_zone $server_name zone=perserver:10m rate=10r/s;

server {
    ...
    limit_req zone=perip burst=5 nodelay;
    limit_req zone=perserver burst=10;
}
```

These directives are inherited from the previous configuration level if and only if there are no `limit_req` directives defined on the current level.





### limit_req_dry_run

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `limit_req_dry_run` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-------------------------------------|
| Default                                                                                  | `limit_req_dry_run off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location              |

Enables the dry run mode. In this mode, requests processing rate is not limited, however, in the [shared memory zone](#limit-req-zone), the number of excessive requests is accounted as usual.





### limit_req_log_level

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `limit_req_log_level` `info` | `notice` | `warn` | `error`;   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------|
| Default                                                                                  | `limit_req_log_level error;`                                  |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                        |

Sets the desired logging level for cases when the server refuses to process requests due to rate exceeding, or delays request processing. Logging level for delays is one point less than for refusals; for example, if `limit_req_log_level notice` is specified, delays are logged with the `info` level.





### limit_req_status

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `limit_req_status` code;   |
|------------------------------------------------------------------------------------------|----------------------------|
| Default                                                                                  | `limit_req_status 503;`    |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location     |

Sets the status code to return in response to rejected requests.





### limit_req_zone

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `limit_req_zone` key `zone=`name:size `rate=`rate;   |
|------------------------------------------------------------------------------------------|------------------------------------------------------|
| Default                                                                                  | —                                                    |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                                                 |

Sets parameters for a shared memory zone that will keep states for various keys. In particular, the state stores the current number of excessive requests. The key can contain [variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables). Requests with an empty key value are not accounted.

Usage example:

```nginx
limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;
```

Here, the states are kept in a 10 megabyte zone `one`, and an average request processing rate for this zone cannot exceed 1 request per second.

A client IP address serves as a key. Note that instead of `$remote_addr`, the `$binary_remote_addr` variable is used here.

The `$binary_remote_addr` variable's size is always 4 bytes for IPv4 addresses or 16 bytes for IPv6 addresses. The stored state always occupies 64 bytes on 32-bit platforms and 128 bytes on 64-bit platforms.

One megabyte zone can keep about 16 thousand 64-byte states or about 8 thousand 128-byte states.

If the zone storage is exhausted, the least recently used state is removed. If even after that a new state cannot be created, the request is terminated with an [error](#limit-req-status).

The `rate` is specified in requests per second (r/s). If a rate of less than one request per second is desired, it is specified in request per minute (r/m). For example, half-request per second is 30r/m.



## Built-in Variables



### `$limit_req_status`

keeps the result of limiting the request processing rate: `PASSED`,
`DELAYED`, `REJECTED`, `DELAYED_DRY_RUN`, or
`REJECTED_DRY_RUN`


# https://en.angie.software/angie/docs/configuration/modules/http/http_log.md





# Log

The module writes request logs in the specified format.

Logs are written in the context of a `location` where processing ends. This may be a `location` different from the original one if an [internal redirect](https://en.angie.software//angie/docs/configuration/modules/http/index.md#internal) occurs during request processing.



## Configuration Example

```nginx
log_format compression '$remote_addr - $remote_user [$time_local] '
                       '"$request" $status $bytes_sent '
                       '"$http_referer" "$http_user_agent" "$gzip_ratio"';

access_log /spool/logs/angie-access.log compression buffer=32k;
```



## Directives





### access_log

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `access_log` path [format [`buffer=`size] [`gzip=`level]] [`flush=`time] [`if=`condition]];

`access_log` `off`;                                                      |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `access_log logs/access.log combined;`
(path depends on the [build parameter](https://en.angie.software//angie/docs/installation/sourcebuild.md#paths) `--http-log-path`) |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location, if in location, limit_except                                                                                                                          |

Sets the path, format and buffered write settings for the log. Multiple logs can be used at the same configuration level. Logging to [syslog](https://en.angie.software//angie/docs/configuration/processing.md#syslog-logging) is configured by specifying the "syslog:" prefix in the first parameter. The special value off cancels all access_log directives for the current level. If no format is specified, the predefined "combined" format is used.

If the buffer size is specified using the `buffer` parameter or the `gzip` parameter is specified, writing will be buffered.

#### WARNING
The buffer size must not exceed the size of an atomic write to a disk file. For FreeBSD this size is unlimited.

When buffering is enabled, data is written to the file:

* if the next log line does not fit in the buffer;
* if the data in the buffer has been there longer than the time interval specified by the flush parameter;
* when [reopening the log file](https://en.angie.software//angie/docs/configuration/runtime.md#log-rotation) or terminating the worker process.

If the `gzip` parameter is specified, the buffer will be compressed before writing to the file. The compression level can be set in the range from 1 (faster, but worse compression) to 9 (slower, but better compression). By default, a buffer size of 64K bytes and compression level 1 are used. Data is compressed in atomic blocks, and at any time the log file can be decompressed or read using the **zcat** utility.

Example:

```nginx
access_log /path/to/log.gz combined gzip flush=5m;
```

#### NOTE
For gzip compression of logs support, Angie must be built with the zlib library.

The file path can contain [variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables), but such logs have some limitations:

* the [user](https://en.angie.software//angie/docs/configuration/modules/core.md#user) under whose credentials the worker processes run must have permissions to create files in the directory with such logs;
* buffering does not work;
* the file is opened for each log write and closed immediately after writing. However, since descriptors of frequently used files can be stored in cache, during log rotation within the time specified by the valid parameter of the [open_log_file_cache](#open-log-file-cache) directive, writing may continue to the old file.
* for each log write, the existence of the root directory for the request is checked — if this directory does not exist, the log is not created. Therefore [root](https://en.angie.software//angie/docs/configuration/modules/http/index.md#root) and [access_log](#access-log) should be described at the same configuration level:

```nginx
server {
    root       /spool/vhost/data/$host;
    access_log /spool/vhost/logs/$host;
    ...
```

The `if` parameter enables conditional logging. A request will not be logged if the condition evaluation result is `"0"` or an empty string. In the following example, requests with response codes 2xx and 3xx will not be logged:

```nginx
map $status $loggable {
    ~^[23]  0;
    default 1;
}

access_log /path/to/access.log combined if=$loggable;
```





### log_format

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `log_format` name [`escape`=:samp:default | `json` | `none`] string ...;   |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|
| Default                                                                                  | `log_format combined "...";`                                               |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                                                                       |

Specifies the log format.

The `escape` parameter allows setting character escaping to `json` or
`default` in variables; by default `default` is used.
The `none` value disables character escaping.

When using `default`, characters """, "\\", and characters with
values less than 32 or greater than 126 are escaped as "\\xXX". If the
variable value is not found, a hyphen "-" will be written to the log as the value.

When using `json`, all characters not allowed in JSON
strings are escaped: characters """ and "\\" are escaped as "\\"" and "\\\\", characters with
values less than 32 are escaped as "\\n", "\\r", "\\t", "\\b", "\\f", or
"\\u00XX".

Header lines sent to the client start with the prefix `sent_http_`,
for example, `$sent_http_content_range`.

The predefined format `combined` always exists in the configuration:

```nginx
log_format combined '$remote_addr - $remote_user [$time_local] '
                    '"$request" $status $body_bytes_sent '
                    '"$http_referer" "$http_user_agent"';
```





### open_log_file_cache

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `open_log_file_cache` `max=`N [`inactive=`time] [`min_uses=`N] [`valid=`time];

`open_log_file_cache` `off`;   |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `open_log_file_cache off;`                                                                                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                 |

Defines a cache that stores file descriptors of frequently used logs whose names are specified using variables. Parameters:

| `max`      | Sets the maximum number of descriptors in the cache; when the cache overflows, the least recently used (LRU) descriptors are closed.                                         |
|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `inactive` | Sets the time after which a cached descriptor is closed if it has not been accessed during this time.
Default is 10 seconds.                                             |
| `min_uses` | Sets the minimum number of file uses during the time specified by the `inactive` parameter, after which the file descriptor will remain open in the cache.
Default is 1. |
| `valid`    | Specifies after what time to check that the file still exists under the same name.
Default is 60 seconds.                                                                |
| `off`      | Disables caching.                                                                                                                                                            |

Usage example:

```nginx
open_log_file_cache max=1000 inactive=20s valid=1m min_uses=2;
```


# https://en.angie.software/angie/docs/configuration/modules/http/http_map.md





# Map

Creates variables whose values depend on values of other variables.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by
default; it can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-http_map_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
map $http_host $name {
    hostnames;

    default       0;

    example.com   1;
    *.example.com 1;
    example.org   2;
    *.example.org 2;
    .example.net  3;
    wap.*         4;
}

map $http_user_agent $mobile {
    default       0;
    "~Opera Mini" 1;
}
```



## Directives





### map

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `map` string $variable { ... }   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | —                                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                             |

Creates a new variable.
Its value depends on the first parameter, specified as a [string with variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables),
for example:

```nginx
set $var1 "foo";
set $var2 "bar";

map $var1$var2 $new_variable {
    default "foobar_value";
}
```

Here, the variable `$new_variable` will have a value
composed of the two variables `$var1` and `$var2`,
or a default value if these variables are not defined.

#### NOTE
Since variables are evaluated only when they are used, the mere declaration even of a large number of "map" variables does not add any extra costs to request processing.

Parameters inside the `map` block specify a mapping between source and resulting values.

Source values are specified as strings or regular expressions.

Strings are matched ignoring the case.

A regular expression should either start with a `~` symbol for a case-sensitive matching, or with the `~*` symbols for case-insensitive matching. A regular expression can contain named and positional captures that can later be used in other directives along with the resulting variable.

If a source value matches one of the names of special parameters described below, it should be prefixed with the `\` symbol.

The resulting value can contain text, variable and their combination.

The following special parameters are also supported:

| `default` value   | sets the resulting value if the source value matches none of the specified variants. When default is not specified, the default resulting value will be an empty string.   |
|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `hostnames`       | indicates that source values can be hostnames with a prefix or suffix mask. This parameter should be specified before the list of values.                                  |

For example,

```nginx
*.example.com 1;
example.*     1;
```

The following two records

```nginx
example.com   1;
*.example.com 1;
```

can be combined:

```nginx
.example.com  1;
```

| `include` file   | includes a file with values. There can be several inclusions.   |
|------------------|-----------------------------------------------------------------|
| `volatile`       | indicates that the variable is not cacheable.                   |

If the source value matches more than one of the specified variants, e.g. both a mask and a regular expression match, the first matching variant will be chosen, in the following order of priority:

1. String value without a mask
2. Longest string value with a prefix mask, e.g. `*.example.com`
3. Longest string value with a suffix mask, e.g. `mail.*`
4. First matching regular expression (in order of appearance in a configuration file)
5. Default value (`default`)





### map_hash_bucket_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `map_hash_bucket_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `map_hash_bucket_size 32|64|128;`                                                                                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                                                                                                                  |

Sets the bucket size for the [map](#id1) variables hash tables. Default value depends on the processor's cache line size. The details of setting up hash tables are provided [separately](https://en.angie.software//angie/docs/configuration/configfile.md#configure-hashes).





### map_hash_max_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `map_hash_max_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `map_hash_max_size 2048;`                                                                                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                                                                                                               |

Sets the maximum size of the [map](#id1) variables hash tables. The details of setting up hash tables are provided [separately](https://en.angie.software//angie/docs/configuration/configfile.md#configure-hashes).


# https://en.angie.software/angie/docs/configuration/modules/http/http_memcached.md





# Memcached

The module is used to obtain responses from a memcached server. The key is set in the [$memcached_key](#v-memcached-key) variable. A response should be put in memcached in advance by means external to Angie.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by
default; it can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-http_memcached_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
server {
    location / {
        set            $memcached_key "$uri?$args";
        memcached_pass host:11211;
        error_page     404 502 504 = @fallback;
    }

    location @fallback {
        proxy_pass     http://backend;
    }
}
```



## Directives





### memcached_bind

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `memcached_bind` address [`transparent`] | `off`;   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------|
| Default                                                                                  | —                                                   |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                              |

Makes outgoing connections to a memcached server originate from the specified local IP address with an optional port. Parameter value can contain [variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables). The special value `off` cancels the effect of the memcached_bind directive inherited from the previous configuration level, which allows the system to auto-assign the local IP address and port.

By default, this value is evaluated once when the request is initialized, before
a memcached server is selected. In Angie PRO, evaluation happens after each
memcached server selection (including retries), so the bind address can depend
on the selected server; for example, via the `$upstream_current_addr`
variable. If the evaluated value is empty, no binding is made.

The `transparent` parameter allows outgoing connections to a memcached
server originate from a non-local IP address, for example, from a real IP
address of a client:

```nginx
memcached_bind $remote_addr transparent;
```

In order for this parameter to work, it is usually necessary to run Angie worker processes with the [superuser](https://en.angie.software//angie/docs/configuration/modules/core.md#user) privileges. On Linux it is not required as if the `transparent` parameter is specified, worker processes inherit the CAP_NET_RAW capability from the master process.

#### NOTE
It is necessary to configure kernel routing table to intercept network traffic from the memcached server.





### memcached_buffer_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `memcached_buffer_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `memcached_buffer_size 4k|8k;`                                                                                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                 |

Sets the size of the buffer used for reading the first part of the response received from the memcached server. The response is passed to the client synchronously, as soon as it is received.





### memcached_connect_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `memcached_connect_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `memcached_connect_timeout 60s;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                     |

Defines a timeout for establishing a connection with a memcached server. It should be noted that this timeout cannot usually exceed 75 seconds.

#### NOTE
This timeout does not govern idle connections: how long an already-open one
is kept for reuse is set by [keepalive_timeout](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive-timeout) in an upstream block
whose connections are cached with [keepalive](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive).





### memcached_gzip_flag

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `memcached_gzip_flag` flag;   |
|------------------------------------------------------------------------------------------|-------------------------------|
| Default                                                                                  | —                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location        |

Enables the test for the flag presence in the memcached server response and sets the `Content-Encoding` response header field to "gzip" if the flag is set.





### memcached_next_upstream

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `memcached_next_upstream` `error` | `timeout` | `invalid_response` | `not_found` | `off` ...;   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------|
| Default                                                                                  | `memcached_next_upstream error timeout;`                                                        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                          |

Specifies in which cases a request should be passed to the next server in the [upstream pool](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream):

| `error`            | an error occurred while establishing a connection with the server, passing a request to it, or reading the response header;      |
|--------------------|----------------------------------------------------------------------------------------------------------------------------------|
| `timeout`          | a timeout has occurred while establishing a connection with the server, passing a request to it, or reading the response header; |
| `invalid_response` | a server returned an empty or invalid response;                                                                                  |
| `not_found`        | a response was not found on the server;                                                                                          |
| `off`              | disables passing a request to the next server.                                                                                   |

#### NOTE
One should bear in mind that passing a request to the next server is only possible if nothing has been sent to a client yet. That is, if an error or timeout occurs in the middle of the transferring of a response, fixing this is impossible.

The directive also defines what is considered an [unsuccessful attempt](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) of communication with a server.

| `error`, `timeout`, `invalid_response`   | always considered unsuccessful attempts, even if they are not specified in the directive   |
|------------------------------------------|--------------------------------------------------------------------------------------------|
| `not_found`                              | never considered an unsuccessful attempt                                                   |

Passing a request to the next server can be limited by the [number of tries](#memcached-next-upstream-tries) and by [time](#memcached-next-upstream-timeout).





### memcached_next_upstream_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `memcached_next_upstream_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `memcached_next_upstream_timeout 0;`                                                                                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                           |

Limits the time during which a request can be passed to the [next](#memcached-next-upstream) server.

| `0`   | turns off this limitation   |
|-------|-----------------------------|





### memcached_next_upstream_tries

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `memcached_next_upstream_tries` number;   |
|------------------------------------------------------------------------------------------|-------------------------------------------|
| Default                                                                                  | `memcached_next_upstream_tries 0;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                    |

Limits the number of possible tries for passing a request to the [next](#memcached-next-upstream) server.

| `0`   | turns off this limitation   |
|-------|-----------------------------|





### memcached_pass

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `memcached_pass` address;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| Default                                                                                  | —                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | location, if in location    |

Sets the memcached server address. The address can be specified as a domain name or IP address, and a port:

```nginx
memcached_pass localhost:11211;
```

or as a UNIX domain socket path:

```nginx
memcached_pass unix:/tmp/memcached.socket;
```

If a domain name resolves to several addresses, all of them will be used in a round-robin fashion. In addition, an address can be specified as a [server group](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream).

#### NOTE
If `memcached_pass` is placed in a `location` whose prefix ends with a slash
(for example, `location /name/`),
and the [auto_redirect](https://en.angie.software//angie/docs/configuration/modules/http/index.md#auto-redirect) directive is set to `default`,
requests without a trailing slash will be redirected (`/name -> /name/`).





### memcached_read_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `memcached_read_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `memcached_read_timeout 60s;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                  |

Defines a timeout for reading a response from the memcached server. The timeout is set only between two successive read operations, not for the transmission of the whole response. If the memcached server does not transmit anything within this time, the connection is closed.





### memcached_send_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `memcached_send_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `memcached_send_timeout 60s;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                  |

Sets a timeout for transmitting a request to the memcached server. The timeout is set only between two successive write operations, not for the transmission of the whole request. If the memcached server does not receive anything within this time, the connection is closed.





### memcached_socket_keepalive

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `memcached_socket_keepalive` `on` | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------------------------|
| Default                                                                                  | `memcached_socket_keepalive off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                       |

Configures the "TCP keepalive" behavior for outgoing connections to a memcached server.

| `off`   | By default, the operating system's settings are in effect for the socket.   |
|---------|-----------------------------------------------------------------------------|
| `on`    | The SO_KEEPALIVE socket option is turned on for the socket.                 |



## Built-in Variables



### `$memcached_key`

Defines a key for obtaining a response from a memcached server.


# https://en.angie.software/angie/docs/configuration/modules/http/http_metric.md





# Metric

#### Versionadded
Added in version 1.11.0.

The `ngx_http_metric_module` module allows creating arbitrary real-time
calculated metrics. These metric values are stored in shared memory and displayed
in real-time within the `/status/http/metric_zones/` API branch.
Various data aggregation types are supported (counters, histograms, moving averages, etc.)
with grouping by arbitrary keys.

For the response schema, see the
[HTTP metric zone API reference](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-metric-zones).

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by
default; it can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-http_metric_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

Counting API requests:

```nginx
http {
    metric_zone api_requests:1m count;

    server {
        listen 80;

        location /api/ {
            allow 127.0.0.1;
            deny all;
            api /status/;

            metric api_requests $http_user_agent on=request;
        }
    }
}
```

If a request is made to `/api/` with this configuration:

```console
$ curl 127.0.0.1/api/ --user-agent "Firefox"
```

The `api_requests` metric is updated in real-time:

```json
{
    "http": {
       "metric_zones": {
           "api_requests": {
               "discarded": 0,
               "metrics": {
                   "Firefox": 1
               }
           }
       }
    }
}
```



## Directives





### metric

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `metric` name key=value [`on`=`request`| `response`| `end`];   |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------|
| Default                                                                                  | —                                                              |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                         |

Calculates the value of the metric for the specified shared memory zone name.

Parameters:

- key — an arbitrary string (often a [variable](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables)) used for grouping values.
  : Maximum length is 255 bytes; longer keys are truncated. In API output,
    Angie appends `...` to every 255-byte key, including one whose
    original length was exactly 255 bytes. If the key itself
    contains one or more `=` characters, only the substring after the
    last `=` is treated as value; everything before it becomes part
    of the key;
- value — a number (can be a variable) processed by the selected mode.
  : If omitted, it defaults to `0`. If the parameter cannot be
    converted to a number, it defaults to `1`;
- `on` — an optional parameter specifying when the metric is calculated:
  - If `on=request`, calculation occurs when the request is received;
  - If `on=response`, calculation occurs during response preparation;
  - If `on=end` (default), calculation occurs after the response is sent.

#### NOTE
In the case of internal redirection, metrics at the `on=request`
stage are calculated in the original `location`. However,
`on=response` and `on=end` metrics will be calculated
in the new `location`.

Example usage:

```nginx
metric requests $http_user_agent=$request_time;
```

#### NOTE
Metrics with an empty key or an invalid `key=value` pair are ignored.
An omitted value is treated as `0`:

```nginx
metric foo $bar;  # Equivalent to $bar=0
```

This is useful, for example, for the `count` mode, which ignores
numerical values and simply reacts to the fact that a metric was updated.

#### NOTE
Remember that variables are evaluated in different phases. For example,
it is impossible to use `$bytes_sent` (bytes sent to the client)
with `on=request` (when the request is received).





### metric_complex_zone

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `metric_complex_zone` name:size [`expire`=`on`| `off`] [`discard_key`=`name`] { ... }   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
| Default                                                                                  | —                                                                                       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                                                                                    |

Defines a complex metric — a set of metrics with independent modes.
Each line in the block body defines a submetric name, a mode,
and optional mode parameters.
The zone size must be at least eight system memory pages: 32K where the page
size is 4K.

Example usage:

```nginx
metric_complex_zone requests:1m expire=on discard_key="old" {
    # submetric name   mode          parameters
    min_time           min;
    avg_time           average exp   factor=60;
    max_time           max;
    total              count;
}
```

In the API tree, such a complex metric template looks as follows:

```json
{
    "discarded": 3,
    "metrics": {
        "key1": {
            "min_time": 20,
            "avg_time": 50,
            "max_time": 80,
            "total": 2
        },
        "old": {
             "min_time": 3,
             "avg_time": 40,
             "max_time": 152,
             "total": 80
        }
    }
}
```





### metric_zone

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `metric_zone` name:size [`expire`=`on`| `off`] [`discard_key`=`name`] mode [parameters];   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|
| Default                                                                                  | —                                                                                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                                                                                       |

Creates a shared memory zone of the specified size with the given name
to store metrics. The zone name serves as a node in the
`/status/http/metric_zones/` branch.
The zone size must be at least eight system memory pages: 32K where the page
size is 4K.

Parameters:

- `expire=` — behavior when the zone is full:
  - If `on`, the oldest metrics (by update time) are discarded to
    : free memory for new ones;
  - If `off` (default) — new incoming metrics are discarded,
    : preserving existing entries.
- `discard_key=` — defines a metric with the key name
  : where values of discarded metrics are accumulated. By default, no such
    metric is created. Reserved key cannot be updated manually.
- mode — data processing algorithm (see the [Operation Modes](#metric-modes) section);
- parameters — additional settings for the selected mode
  : (e.g., `factor` for `average exp`).

Example usage:

```nginx
metric_zone request_time:1m max;
```

In the API tree, the shared memory zone template looks as follows:

```json
{
    "discarded": 0,
    "metrics": {
        "key1": 123,
        "key2": 10.5
    }
}
```

#### NOTE
In a 1 MB zone, with a key size of 39 bytes and a single metric mode,
approximately 8,000 unique key entries can be stored.



## Operation Modes

List of available metric operation modes:

* `count` — counter;
* `gauge` — gauge (increment/decrement);
* `last` — the last received value;
* `min` — minimum value;
* `max` — maximum value;
* `average exp` — exponential moving average (EMA) (parameter `factor`);
* `average mean` — mean over a window (parameters `window` and `count`);
* `histogram` — distribution across "buckets" (a list of threshold values).

The examples below use the `/api/` endpoint from the
[configuration example](#configuration-example-30). Each result is
available under `/api/http/metric_zones//metrics/`.



### count

Each metric update increments the counter by `1`, regardless of the
supplied value.

Default value — `0`.

Examples:

```nginx
metric_zone count:1m count;

# As part of a complex metric:
#
# metric_complex_zone count:1m {
#     some_metric_name  count;
# }

server {
    listen 80;

    location /metric/ {
        metric count KEY;
    }

    location ~ ^/metric/set/(.+)$ {
        metric count KEY=$1;
    }

}
```

Updating the metric:

```console
$ curl 127.0.0.1/metric/
$ curl 127.0.0.1/metric/set/1
$ curl 127.0.0.1/metric/set/23
$ curl 127.0.0.1/metric/set/-32
```

Expected metric value in the API:

```json
{
    "KEY": 4
}
```



### gauge

The gauge increases or decreases its value depending on the sign of the
passed number. A positive value increases the counter, while a negative
value decreases it. A value of `0` does not change the counter.

Default value — `0`.

Examples:

```nginx
metric_zone gauge:1m gauge;

# As part of a complex metric:
#
# metric_complex_zone gauge:1m {
#     some_metric_name  gauge;
# }

server {
    listen 80;

    location /metric/ {
        metric gauge KEY;
    }

    location ~ ^/metric/set/(.+)$ {
        metric gauge KEY=$1;
    }

}
```

Updating the metric:

```console
$ curl 127.0.0.1/metric/
```

Expected metric value in the API:

```json
{
    "KEY": 0
}
```

Further updates:

```console
$ curl 127.0.0.1/metric/set/5
$ curl 127.0.0.1/metric/set/-5
$ curl 127.0.0.1/metric/set/8
```

Expected metric value in the API:

```json
{
    "KEY": 8
}
```



### last

Stores the last received value without any aggregation. If value is
omitted, `0` is used.

Examples:

```nginx
metric_zone last:1m last;

# As part of a complex metric:
#
# metric_complex_zone last:1m {
#     some_metric_name  last;
# }

server {
    listen 80;

    location /metric/ {
        metric last KEY;
    }

    location ~ ^/metric/set/(.+)$ {
        metric last KEY=$1;
    }

}
```

Updating the metric:

```console
$ curl 127.0.0.1/metric/
```

Expected metric value in the API:

```json
{
    "KEY": 0
}
```

Further updates:

```console
$ curl 127.0.0.1/metric/set/8000
$ curl 127.0.0.1/metric/set/37
$ curl 127.0.0.1/metric/set/-3.5
```

Expected metric value in the API:

```json
{
   "KEY": -3.5
}
```



### min

Saves the minimum of two values — the currently stored value and the new one.

Examples:

```nginx
metric_zone min:1m min;

# As part of a complex metric:
#
# metric_complex_zone min:1m {
#     some_metric_name  min;
# }

server {
    listen 80;

    location /metric/ {
        metric min KEY;
    }

    location ~ ^/metric/set/(.+)$ {
        metric min KEY=$1;
    }

}
```

Updating the metric:

```console
$ curl 127.0.0.1/metric/set/42.999
$ curl 127.0.0.1/metric/set/-512
$ curl 127.0.0.1/metric/set/1
$ curl 127.0.0.1/metric/
```

Expected metric value in the API:

```json
{
    "KEY": -512
}
```



### max

Saves the maximum of two values — the currently stored value and the new one.

Examples:

```nginx
metric_zone max:1m max;

# As part of a complex metric:
#
# metric_complex_zone max:1m {
#     some_metric_name  max;
# }

server {
    listen 80;

    location /metric/ {
        metric max KEY;
    }

    location ~ ^/metric/set/(.+)$ {
        metric max KEY=$1;
    }

}
```

Updating the metric:

```console
$ curl 127.0.0.1/metric/set/42.999
$ curl 127.0.0.1/metric/set/-512
$ curl 127.0.0.1/metric/set/1
$ curl 127.0.0.1/metric/
```

Expected metric value in the API:

```json
{
    "KEY": 42.999
}
```



### average exp

Calculates the average value using the
[exponential smoothing](https://en.wikipedia.org/wiki/Exponential_smoothing) algorithm.

Accepts an optional parameter `factor=` — a coefficient determining
how much the new value influences the average. Integer values from `0` to
`99` are allowed. Default is `90`.

The higher the coefficient, the more weight new values have. If you specify
`90`, the result will be `90%` of the new value and `10%`
of the previous average.

Examples:

```nginx
metric_zone avg_exp:1m average exp factor=60;

# As part of a complex metric:
#
# metric_complex_zone avg_exp:1m {
#     some_metric_name  average exp  factor=60;
# }

server {
    listen 80;

    location ~ ^/metric/set/(.+)$ {
        metric avg_exp KEY=$1;
    }

}
```

Updating the metric:

```console
$ curl 127.0.0.1/metric/set/100
$ curl 127.0.0.1/metric/set/200
$ curl 127.0.0.1/metric/set/0
$ curl 127.0.0.1/metric/set/8
$ curl 127.0.0.1/metric/set/30
```

Expected metric value in the API:

```json
{
    "KEY": 30.16
}
```



### average mean

Calculates the arithmetic mean. Accepts optional parameters
`window=` and `count=`, defining the
time interval and sample size for averaging, respectively.
Defaults: `window=off` (entire sample used) and `count=10`.

#### NOTE
For example, `window=5s` will only consider events from the last 5 seconds.
The `window` parameter cannot be `0`. The `count=number`
parameter controls the sample size (cached values) for a smoother mean calculation.

Examples:

```nginx
metric_zone avg_mean:1m average mean window=5s count=8;

# As part of a complex metric:
#
# metric_complex_zone avg_mean:1m {
#     some_metric_name  average mean  window=5s count=8;
# }

server {
    listen 80;

    location ~ ^/metric/set/(.+)$ {
        metric avg_mean KEY=$1;
    }

}
```

Updating the metric:

```console
$ curl 127.0.0.1/metric/set/0.1
$ curl 127.0.0.1/metric/set/0.1
$ curl 127.0.0.1/metric/set/0.4
$ curl 127.0.0.1/metric/set/10
$ curl 127.0.0.1/metric/set/1
$ curl 127.0.0.1/metric/set/1
```

Expected metric value in the API:

```json
{
    "KEY": 2.1
}
```

If you wait 5 seconds from the last update, the expected value will be:

```json
{
    "KEY": 0
}
```



### histogram

Creates a set of "buckets," incrementing the relevant counter if the new
value does not exceed the bucket threshold. Parameters are provided as
a list of numerical thresholds. Useful for analyzing distributions,
such as response times.

Mandatory parameters are numbers — the threshold values of the buckets,
typically listed in ascending order.

#### NOTE
The bucket value `inf` or `+Inf` can be used to capture all
values exceeding the highest specified bucket.

Examples:

```nginx
metric_zone hist:1m histogram 0.1 0.2 0.5 1 2 inf;

# As part of a complex metric:
#
# metric_complex_zone hist:1m {
#     some_metric_name  histogram  0.1 0.2 0.5 1 2 inf;
# }

server {
    listen 80;

    location ~ ^/metric/set/(.+)$ {
        metric hist KEY=$1;
    }
}
```

Updating the metric:

```console
$ curl 127.0.0.1/metric/set/0.25
```

Expected metric value in the API:

```json
{
    "KEY": {
        "0.1": 0,
        "0.2": 0,
        "0.5": 1,
        "1": 1,
        "2": 1,
        "inf": 1
    }
}
```

Further updates:

```console
$ curl 127.0.0.1/metric/set/2
```

Expected metric value in the API:

```json
{
    "KEY": {
        "0.1": 0,
        "0.2": 0,
        "0.5": 1,
        "1": 1,
        "2": 2,
        "inf": 2
    }
}
```

Further update:

```console
$ curl 127.0.0.1/metric/set/1000
```

Expected metric value in the API:

```json
{
    "KEY": {
       "0.1": 0,
       "0.2": 0,
       "0.5": 1,
       "1": 1,
       "2": 2,
       "inf": 3
    }
}
```



## Built-in Variables

Variables are created for each metric:

- `$metric_`
- `$metric__key`
- `$metric__value`

For complex metrics, an additional variable is added:

- `$metric__value_`



### `$metric_`

Similar to the [metric](#id1) directive, the `$metric_`
variable setter can be used to update a metric. Calculation occurs during the
[Rewrite](https://angie.software/angie/docs/configuration/modules/http/http_rewrite/) phase,
allowing metric processing from the [njs](https://angie.software/angie/docs/configuration/modules/http/http_js/) module, for example.

The setter accepts a key with an optional `=value` suffix. Without the
suffix, the value is `0`. The key and value can contain text, variables,
or combinations of both.

Example usage:

```nginx
http {
    metric_zone counter:1m count;

    # At this point, the $metric_counter variable is added

    server {
        listen 80;

        location /metric/ {
            set $metric_counter $http_user_agent;  # Equivalent to $http_user_agent=0
        }

        location /api/ {
            allow 127.0.0.1;
            deny all;
            api /status/http/metric_zones/counter/;
        }
    }
}
```

Calculating metrics using the
[njs](https://angie.software/angie/docs/configuration/modules/http/http_js/) module:

```nginx
http {
    js_import metrics.js;

    resolver 127.0.0.53;

    metric_complex_zone requests:1m {
        min_time        min;
        max_time        max;
        total           count;
    }

    location /metric/ {
        js_content metrics.js_request;
        js_fetch_trusted_certificate /path/to/ISRG_Root_X1.pem;
    }

    location /api/ {
        allow 127.0.0.1;
        deny all;
        api /static/http/metric_zones/requests/;
    }
}
```

File `metrics.js`:

```js
async function js_request(r) {
    let start_time = Date.now();

    let results = await Promise.all([ngx.fetch('https://google.com/'),
                                     ngx.fetch('https://google.ru/')]);

    // Using the $metric_requests variable setter
    r.variables.metric_requests = `google=${Date.now() - start_time}`;
}

export default {js_request};
```

After several requests to `location /metric/`, the values might look like this:

```json
{
    "discarded": 0,
    "metrics": {
        "google": {
            "min_time": 70,
            "max_time": 432,
            "total": 6
        }
    }
}
```

#### NOTE
After setting the variable, you can retrieve its value; it will equal
the key together with the newly calculated metric value, in the
`key=value` format — not the literal string that was assigned.

Additionally, the value stored in the `$metric__key` variable
will change to the specified key.





### `$metric__key` and `$metric__value`

The `$metric__key` and `$metric__value` variables
define the key and value respectively. The metric update occurs when the
`$metric__value` is set, provided that the key in
`$metric__key` has already been defined.

#### NOTE
For complex metrics, the submetric values in the `$metric__value`
variable are joined using a `", "` separator.

Example usage:

```nginx
http {
    metric_zone gauge:1m gauge;

    # The variables $metric_gauge, $metric_gauge_key, and $metric_gauge_value are added here.

    metric_complex_zone complex:1m {
        hist histogram 1 2 3;
        avg  average exp;
    }

    # $metric_complex, $metric_complex_key, and $metric_complex_value are added here.

    server {
        listen 80;

        location /gauge/ {
            set $metric_gauge_key "foo";
            set $metric_gauge_value 1;

            # Or: set $metric_gauge foo=1;

            return 200 "Updated with '$metric_gauge'\nValue='$metric_gauge_value'\n";
        }

        location /complex/ {
            set $metric_complex_key "foo";
            set $metric_complex_value 3;

            # Or: set $metric_complex foo=3;

            return 200 "Updated with '$metric_complex'\nValue='$metric_complex_value'\n";
        }
    }
}
```

With this configuration, a request to `/gauge/` yields:

```console
$ curl 127.0.0.1/gauge/
Updated with 'foo=1'
Value='1'
```

For `/complex/`:

```console
$ curl 127.0.0.1/complex/
Updated with 'foo=0 0 1, 3'
Value='0 0 1, 3'
```

#### NOTE
If an empty string is assigned to `$metric__value`, the value is
recognized as `0`. If the string consists of characters that cannot be
converted to a number, it is recognized as `1`.

Calculation occurs only after both `$metric__key` and
`$metric__value` have been set.

In this case, the value stored in `$metric_` becomes equal
to the key together with the newly calculated metric value, in the
`key=value` format.

The value in `$metric__key` represents the last key specified
via variables.

The value in `$metric__value` represents the last calculated
value for the key set in `$metric__key`.



### `$metric__value_`

For complex metrics, the value of a specific submetric can be retrieved
using the `$metric__value_` variable, where
 is the name of the submetric.

Example usage:

```nginx
http {
    metric_complex_zone foo:1m {
        count count;
        min   min;
        avg   average exp;
    }

    # Adds $metric_foo, $metric_foo_key, $metric_foo_value,
    # and $metric_foo_value_count, $metric_foo_value_min, $metric_foo_value_avg.

    server {
        listen 80;

        location /foo/ {
            set $metric_foo_key   bar;
            set $metric_foo_value 9;

            # Or: set $metric_foo bar=9;

            return 200 "Updated with '$metric_foo'\nValues='$metric_foo_value'\nCount='$metric_foo_value_count'\n";
        }
    }
}
```

With this configuration, a request to `/foo/` yields:

```console
$ curl 127.0.0.1/foo/
Updated with 'bar=1, 9, 9'
Values='1, 9, 9'
Count='1'
```



## Additional Examples



### Monitoring HTTP Methods

```nginx
metric_zone http_methods:1m count;

server {
    listen 80;

    location / {
        metric http_methods $request_method;
    }

    location /metrics/ {
        allow 127.0.0.1;
        deny all;
        api /status/http/metric_zones/http_methods/metrics/;
    }
}
```

Response:

```json
{
    "GET": 65,
    "POST": 20,
    "PUT": 10,
    "DELETE": 5
}
```



### Upstream Response Time Distribution

```nginx
metric_zone upstream_time:10m expire=on histogram
    0.05 0.1 0.3 0.5 1 2 5 10 inf;

server {
    listen 80;

    location /backend/ {
        proxy_pass http://backend;
        metric upstream_time $upstream_addr=$upstream_response_time on=end;
    }

    location /metrics/ {
        allow 127.0.0.1;
        deny all;
        api /status/http/metric_zones/upstream_time/;
    }
}
```

Response:

```json
{
    "discarded": 0,
    "metrics": {
        "backend1:8080": {
            "0.05": 12,
            "0.1": 28,
            "0.3": 56,
            "0.5": 78,
            "1": 92,
            "2": 97,
            "5": 99,
            "10": 100,
            "inf": 100
        }
    }
}
```



### Active Connections

```nginx
metric_zone active_connections:2m gauge;

server {
    listen 80;
    server_name site1.com;

    location / {
        # Увеличиваем при подключении
        metric active_connections site1=1 on=request;

        # Уменьшаем при завершении
        metric active_connections site1=-1 on=end;
    }
}

server {
    listen 80;
    server_name site2.com;

    location / {
        metric active_connections site2=1 on=request;
        metric active_connections site2=-1 on=end;
    }
}

server {
    listen 8080;

    location /connections/ {
        allow 127.0.0.1;
        deny all;
        api /status/http/metric_zones/active_connections/metrics;
    }
}
```

Response:

```json
{
    "site1": 42,
    "site2": 17
}
```



## Prometheus Support

Angie includes a built-in [Prometheus](https://en.angie.software//angie/docs/configuration/modules/http/http_prometheus.md#http-prometheus) module for
displaying metrics in
[Prometheus format](https://prometheus.io/docs/instrumenting/exposition_formats/),
which supports custom metrics.

As an integration example, consider the following configuration:

```nginx
http {
    # Creating the "upload" metric
    metric_complex_zone upload:1m discard_key="other" {
        stats    histogram 64 256 1024 4096 16384 +Inf;
        sum      gauge;
        count    count;
        avg_size average exp;
    }

    # Describing the Prometheus template for the "upload" metric
    prometheus_template upload_metric {
        'stats{le="$1"}' $p8s_value
                         path=~^/http/metric_zones/upload/metrics/angie/stats/(.+)$
                         type=histogram;

        'stats_sum'      $p8s_value
                         path=/http/metric_zones/upload/metrics/angie/sum;
        'stats_count'    $p8s_value
                         path=/http/metric_zones/upload/metrics/angie/count;

        'avg_size'       $p8s_value
                         path=/http/metric_zones/upload/metrics/angie/avg_size;
    }

    server {
        listen 80;

        # Updating the metric
        location ~ ^/upload/(.*)$ {
            api /status/http/metric_zones/upload/metrics/angie/;
            metric upload angie=$1 on=request;
        }

        # Target for metric scraping
        location /prometheus/upload_metric/ {
            prometheus upload_metric;
        }
    }
}
```

After several requests to `/upload/...`:

```console
$ curl 127.0.0.1/upload/16384
$ curl 127.0.0.1/upload/64448
$ curl 127.0.0.1/upload/64
$ curl 127.0.0.1/upload/1028
$ curl 127.0.0.1/upload/1028
```

The metric values will be:

```json
{
    "stats": {
        "64": 1,
        "256": 1,
        "1024": 1,
        "4096": 3,
        "16384": 4,
        "+Inf": 5
    },

    "sum": 82952,
    "count": 5,
    "avg_size": 1077.9376
}
```

In [Prometheus format](https://prometheus.io/docs/instrumenting/exposition_formats/),
the metric is available at `/prometheus/upload_metric/`:

```text
# Angie Prometheus template "upload_metric"
# TYPE stats histogram
stats{le="64"} 1
stats{le="256"} 1
stats{le="1024"} 1
stats{le="4096"} 3
stats{le="16384"} 4
stats{le="+Inf"} 5
stats_sum 82952
stats_count 5
avg_size 1077.9376
```


# https://en.angie.software/angie/docs/configuration/modules/http/http_mirror.md





# Mirror

The module implements mirroring of an original request by creating background mirror subrequests. Responses to mirror subrequests are ignored.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by
default; it can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-http_mirror_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
location / {
    mirror /mirror;
    proxy_pass http://backend;
}

location = /mirror {
    internal;
    proxy_pass http://test_backend$request_uri;
}
```



## Directives





### mirror

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `mirror` uri | `off`;   |
|------------------------------------------------------------------------------------------|-------------------------|
| Default                                                                                  | `mirror off;`           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location  |

Sets the URI to which an original request will be mirrored. Several mirrors can be specified on the same configuration level.





### mirror_request_body

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `mirror_request_body` `on` | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------------|
| Default                                                                                  | `mirror_request_body on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                |

Indicates whether the client request body is mirrored. When enabled, the client request body will be read prior to creating mirror subrequests. In this case, unbuffered client request body proxying set by the [proxy_request_buffering](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-request-buffering), [fastcgi_request_buffering](https://en.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-request-buffering), [scgi_request_buffering](https://en.angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-request-buffering) and [uwsgi_request_buffering](https://en.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-request-buffering) directives will be disabled.

```nginx
location / {
    mirror /mirror;
    mirror_request_body off;
    proxy_pass http://backend;
}

location = /mirror {
    internal;
    proxy_pass http://log_backend;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_set_header X-Original-URI $request_uri;
}
```


# https://en.angie.software/angie/docs/configuration/modules/http/http_mp4.md





# MP4

The module provides pseudo-streaming server-side support for MP4 files. Such
files typically have the .mp4, .m4v, or .m4a filename extensions.

Pseudo-streaming works in alliance with a compatible media player. The player
sends an HTTP request to the server with the start time specified in the query
string argument (named simply start and specified in seconds), and the server
responds with the stream such that its start position corresponds to the
requested time, for example:

```none
http://example.com/elephants_dream.mp4?start=238.88
```

This allows performing a random seeking at any time, or starting playback in the
middle of the timeline.

To support seeking, H.264-based formats store metadata in a so-called "moov
atom". It is a part of the file that holds the index information for the whole
file.

To start playback, the player first needs to read metadata. This is done by
sending a special request with the `start=0` argument. A lot of encoding
software insert the metadata at the end of the file. This is suboptimal for
pseudo-streaming, because the player has to download the entire file before
starting playback. If the metadata are located at the beginning of the file, it
is enough for Angie to simply start sending back the file contents. If the
metadata are located at the end of the file, Angie must read the entire file and
prepare a new stream so that the metadata come before the media data. This
involves some CPU, memory, and disk I/O overhead, so it is a good idea to
[prepare](https://github.com/flowplayer/flowplayer/wiki/7.1.1-video-file-correction) an
original file for pseudo-streaming in advance, rather than having Angie do this
on every such request.

The module also supports the `end` argument of an HTTP request which sets
the end point of playback. The `end` argument can be specified with the
start argument or separately:

```none
http://example.com/elephants_dream.mp4?start=238.88&end=555.55
```

For a matching request with a non-zero `start` or `end` argument,
Angie will read the metadata from the file, prepare the stream with the
requested time range, and send it to the client. This has the same overhead as
described above.

If the `start` argument points to a non-key video frame, the beginning of
such video will be broken. To fix this issue, the video [can](#mp4-start-key-frame) be prepended with the key frame before `start`
point and with all intermediate frames between them. These frames will be hidden
from playback using an edit list.

If a matching request does not include the `start` and `end`
arguments, there is no overhead, and the file is sent simply as a static
resource. Some players also support byte-range requests, and thus do not require
this module.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module isn't built
by default; it must be enabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--with-http_mp4_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.

#### WARNING
If a third-party `mp4` module was previously used, it should be disabled.

A similar pseudo-streaming support for FLV files is provided by the [FLV](https://en.angie.software//angie/docs/configuration/modules/http/http_flv.md#http-flv) module.



## Configuration Example

```nginx
location /video/ {
    mp4;
    mp4_buffer_size     1m;
    mp4_max_buffer_size 5m;
}
```



## Directives





### mp4

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `mp4`;   |
|------------------------------------------------------------------------------------------|----------|
| Default                                                                                  | —        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | location |

Turns on module processing in a surrounding location.





### mp4_buffer_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `mp4_buffer_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `mp4_buffer_size 512K;`                                                                                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                           |

Sets the initial size of the buffer used for processing MP4 files.





### mp4_limit_rate

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `mp4_limit_rate` `on` | `off` | factor;   |
|------------------------------------------------------------------------------------------|-------------------------------------------|
| Default                                                                                  | `mp4_limit_rate off;`                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                    |

Rate-limits the transfer of the requested MP4 file to the client.
To calculate the limit, the factor is multiplied
by the average bitrate of the file.

- The `off` value disables rate limiting.
- The `on` value sets a factor of `1.1`.
- The limit is applied after reaching the value set by
  [mp4_limit_rate_after](#mp4-limit-rate-after).

The requests are rate limited individually:
if the client opens two connections,
the resulting rate doubles.
In this regard, consider using [limit_conn](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#limit-conn) and accompanying directives.





### mp4_limit_rate_after

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `mp4_limit_rate_after` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `mp4_limit_rate_after 60s;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                |

Sets
(in terms of
[playback time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units))
the amount of media data transferred
that triggers
the rate limit set by
[mp4_limit_rate](#mp4-limit-rate).





### mp4_max_buffer_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `mp4_max_buffer_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `mp4_max_buffer_size 10M;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                               |

During metadata processing, a larger buffer may become necessary. Its size cannot exceed the specified size, or else Angie will return the 500 (Internal Server Error) server error, and log the following message:

> "/some/movie/file.mp4" mp4 moov atom is too large:
> 12583268, you may want to increase mp4_max_buffer_size





### mp4_start_key_frame

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `mp4_start_key_frame` `on` | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------------|
| Default                                                                                  | `mp4_start_key_frame off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                |

Forces output video to always start with a key video frame. If the start argument does not point to a key frame, initial frames are hidden using an mp4 edit list. Edit lists are supported by major players and browsers such as Chrome, Safari, QuickTime and ffmpeg, partially supported by Firefox.


# https://en.angie.software/angie/docs/configuration/modules/http/http_perl.md





# Perl

The module allows writing location and variable handlers in Perl, as well as inserting Perl calls into SSI.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module isn't built
by default; it must be enabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--with-http_perl_module`.

In [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the module is built
[dynamically](https://en.angie.software//angie/docs/installation/index.md#install-dynamicmodules) and is available as a separate
package named `angie-module-perl` or `angie-pro-module-perl`.

In our repositories, the module is built
[dynamically](https://en.angie.software//angie/docs/installation/index.md#install-dynamicmodules)
and is available as a separate package named `angie-module-perl` or `angie-pro-module-perl`;
it can be loaded using the [load_module](https://en.angie.software//angie/docs/configuration/modules/core.md#load-module) directive.

#### NOTE
This module requires Perl version 5.6.1 or higher. The C compiler should be compatible with the one used to build Perl.



## Known Issues

The module is experimental, so anything is possible.

In order for Perl to recompile the modified modules during reconfiguration, it
should be built with the `-Dusemultiplicity=yes` or
`-Dusethreads=yes` parameters. Also, to make Perl leak less memory at run
time, it should be built with the `-Dusemymalloc=no` parameter. To check
the values of these parameters in an already built Perl (preferred values are
specified in the example), run:

```console
$ perl -V:usemultiplicity -V:usemymalloc
usemultiplicity='define';
usemymalloc='n';
```

Note that after rebuilding Perl with the new `-Dusemultiplicity=yes` or
`-Dusethreads=yes` parameters, all binary Perl modules will have to be
rebuilt as well — they will just stop working with the new Perl.

There is a possibility that the main process and then worker processes will grow
in size after every reconfiguration. If the main process grows to an
unacceptable size, the [live upgrade](https://en.angie.software//angie/docs/configuration/runtime.md#service-upgrade) procedure can be
applied without changing the executable file.

While the Perl module is performing a long-running operation, such as resolving
a domain name, connecting to another server, or querying a database, other
requests assigned to the current worker process will not be processed. It is
thus recommended to perform only such operations that have predictable and short
execution time, such as accessing the local file system.



## Configuration Example

```nginx
http {

    perl_modules perl/lib;
    perl_require hello.pm;

    perl_set $msie6 '

        sub {
            my $r = shift;
            my $ua = $r->header_in("User-Agent");

            return "" if $ua =~ /Opera/;
            return "1" if $ua =~ / MSIE [6-9]\.\d+/;
            return "";
        }

    ';

    server {
        location / {
            perl hello::handler;
        }
    }
```

The perl/lib/hello.pm module:

```perl
package hello;

use nginx;

sub handler {
    my $r = shift;

    $r->send_http_header("text/html");
    return OK if $r->header_only;

    $r->print("hello!\n
");

    if (-f $r->filename or -d _) {
        $r->print($r->uri, " exists!\n");
    }

    return OK;
}

1;
__END__
```



## Directives





### perl

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `perl` module :: function | 'sub { ... }';   |
|------------------------------------------------------------------------------------------|----------------------------------------------|
| Default                                                                                  | —                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | location, limit_except                       |

Sets a Perl handler for the given location.





### perl_modules

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `perl_modules` path;   |
|------------------------------------------------------------------------------------------|------------------------|
| Default                                                                                  | —                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                   |

Sets an additional path for Perl modules.





### perl_require

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `perl_require` module;   |
|------------------------------------------------------------------------------------------|--------------------------|
| Default                                                                                  | —                        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                     |

Defines the name of a module that will be loaded during each reconfiguration. Several perl_require directives can be present.





### perl_set

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `perl_set` $variable module :: function | 'sub { ... }';   |
|------------------------------------------------------------------------------------------|------------------------------------------------------------|
| Default                                                                                  | —                                                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                                                       |

Sets a Perl handler for the specified variable.



## Calling Perl from SSI

An SSI command calling Perl has the following format:

```html

```



## The $r Request Object Methods



### `$r->args`

Returns request arguments.



### `$r->filename`

Returns a filename corresponding to the request URI.



### `$r->has_request_body` (handler)

Returns 0 if there is no body in a request. If there is a body, the specified handler is set for the request and 1 is returned. After reading the request body, Angie will call the specified handler. Note that the handler function should be passed by reference. Example:

```perl
package hello;

use nginx;

sub handler {
    my $r = shift;

    if ($r->request_method ne "POST") {
        return DECLINED;
    }

    if ($r->has_request_body(\&post)) {
        return OK;
    }

    return HTTP_BAD_REQUEST;
}

sub post {
    my $r = shift;

    $r->send_http_header;

    $r->print("request_body: \"", $r->request_body, "\"
");
    $r->print("request_body_file: \"", $r->request_body_file, "\"
\n");

    return OK;
}

1;

__END__
```



### `$r->allow_ranges`

Enables the use of byte ranges when sending responses.



### `$r->discard_request_body`

Instructs Angie to discard the request body.



### `$r->header_in` (field)

Returns the value of the specified client request header field.



### `$r->header_only`

Determines whether the whole response or only its header should be sent to the client.



### `$r->header_out` (field, value)

Sets a value for the specified response header field.



### `$r->internal_redirect` (uri)

Does an internal redirect to the specified uri. An actual redirect happens after the Perl handler execution is completed. The method accepts escaped URIs and supports redirections to [named locations](https://en.angie.software//angie/docs/configuration/modules/http/index.md#named-location).



### `$r->log_error` (errno, message)

Writes the specified message into the [error_log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log). If errno is non-zero, an error code and its description will be appended to the message.



### `$r->print` (text, ...)

Passes data to a client.



### `$r->request_body`

Returns the client request body if it has not been written to a temporary file. To ensure that the client request body is in memory, its size should be limited by [client_max_body_size](https://en.angie.software//angie/docs/configuration/modules/http/index.md#client-max-body-size), and a sufficient buffer size should be set using [client_body_buffer_size](https://en.angie.software//angie/docs/configuration/modules/http/index.md#client-body-buffer-size).



### `$r->request_body_file`

Returns the name of the file with the client request body. After the processing, the file should be removed. To always write a request body to a file, [client_body_in_file_only](https://en.angie.software//angie/docs/configuration/modules/http/index.md#client-body-in-file-only) should be enabled.



### `$r->request_method`

Returns the client request HTTP method.



### `$r->remote_addr`

Returns the client IP address.



### `$r->flush`

Immediately sends data to the client.



### `$r->sendfile` (name [, offset [, length ]])

Sends the specified file content to the client. Optional parameters specify the initial offset and length of the data to be transmitted. The actual data transmission happens after the Perl handler has completed.



### `$r->send_http_header` ([type])

Sends the response header to the client. The optional type parameter sets the value of the `Content-Type` response header field. If the value is an empty string, the `Content-Type` header field will not be sent.



### `$r->status` (code)

Sets a response code.



### `$r->sleep` (milliseconds, handler)

Sets the specified handler and stops request processing for the specified time. In the meantime, Angie continues to process other requests. After the specified time has elapsed, Angie will call the installed handler. Note that the handler function should be passed by reference. In order to pass data between handlers, [$r‑>variable()](#p-r-variable) should be used. Example:

```nginx
package hello;

use nginx;

sub handler {
    my $r = shift;

    $r->discard_request_body;
    $r->variable("var", "OK");
    $r->sleep(1000, \&next);

    return OK;
}

sub next {
    my $r = shift;

    $r->send_http_header;
    $r->print($r->variable("var"));

    return OK;
}

1;

__END__
```



### `$r->unescape` (text)

Decodes a text encoded in the "%XX" form.



### `$r->uri`

Returns a request URI.



### `$r->variable` (name [, value ])

Returns or sets the value of the specified variable. Variables are local to each request.


# https://en.angie.software/angie/docs/configuration/modules/http/http_prometheus.md





# Prometheus

Collects Angie [statistics](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#metrics),
based on templates defined in the configuration,
and returns metrics generated from these templates in the
[Prometheus format](https://prometheus.io/docs/instrumenting/exposition_formats/).

#### WARNING
To collect statistics,
enable a shared memory zone in the appropriate contexts using:

- the `zone` directive in [http_upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone)
  or [stream_upstream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-zone);
- the [status_zone](https://en.angie.software//angie/docs/configuration/modules/http/index.md#status-zone) directive;
- the `status_zone` parameter in the [resolver](https://en.angie.software//angie/docs/configuration/modules/http/index.md#resolver) directive.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by
default; it can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-http_prometheus_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

Three metrics for collecting request statistics for server shared memory zones,
combined into the `custom` template and published at the `/p8s` path:

```nginx
http {

    prometheus_template custom {
        'angie_http_server_zones_requests_total{zone="$1"}' $p8s_value
            path=~^/http/server_zones/([^/]+)/requests/total$
            type=counter;

        'angie_http_server_zones_requests_processing{zone="$1"}' $p8s_value
            path=~^/http/server_zones/([^/]+)/requests/processing$
            type=gauge;

        'angie_http_server_zones_requests_discarded{zone="$1"}' $p8s_value
            path=~^/http/server_zones/([^/]+)/requests/discarded$
            type=counter;
    }

    # ...

    server {

        listen 80;

        location =/p8s {
            prometheus custom;
        }

        # ...

    }
}
```



Angie includes a helper file `prometheus_all.conf`
that contains a set of commonly used metrics combined into the `all` template:

### File Contents (Angie)

```nginx

prometheus_template all {

angie_connections_accepted $p8s_value
    path=/connections/accepted
    type=counter
    'help=The total number of accepted client connections.';

angie_connections_dropped $p8s_value
    path=/connections/dropped
    type=counter
    'help=The total number of dropped client connections.';

angie_connections_active $p8s_value
    path=/connections/active
    type=gauge
    'help=The current number of active client connections.';

angie_connections_idle $p8s_value
    path=/connections/idle
    type=gauge
    'help=The current number of idle client connections.';


'angie_slabs_pages_used{zone="$1"}' $p8s_value
    path=~^/slabs/([^/]+)/pages/used$
    type=gauge
    'help=The number of currently used memory pages in a slab zone.';

'angie_slabs_pages_free{zone="$1"}' $p8s_value
    path=~^/slabs/([^/]+)/pages/free$
    type=gauge
    'help=The number of currently free memory pages in a slab zone.';


'angie_slabs_pages_slots_used{zone="$1",size="$2"}' $p8s_value
    path=~^/slabs/([^/]+)/slots/([^/]+)/used$
    type=gauge
    'help=The number of currently used memory slots of a specific size in a slab zone.';

'angie_slabs_pages_slots_free{zone="$1",size="$2"}' $p8s_value
    path=~^/slabs/([^/]+)/slots/([^/]+)/free$
    type=gauge
    'help=The number of currently free memory slots of a specific size in a slab zone.';

'angie_slabs_pages_slots_reqs{zone="$1",size="$2"}' $p8s_value
    path=~^/slabs/([^/]+)/slots/([^/]+)/reqs$
    type=counter
    'help=The total number of attempts to allocate a memory slot of a specific size in a slab zone.';

'angie_slabs_pages_slots_fails{zone="$1",size="$2"}' $p8s_value
    path=~^/slabs/([^/]+)/slots/([^/]+)/fails$
    type=counter
    'help=The number of unsuccessful attempts to allocate a memory slot of a specific size in a slab zone.';


'angie_resolvers_queries{zone="$1",type="$2"}' $p8s_value
    path=~^/resolvers/([^/]+)/queries/([^/]+)$
    type=counter
    'help=The number of queries of a specific type to resolve in a resolver zone.';

'angie_resolvers_sent{zone="$1",type="$2"}' $p8s_value
    path=~^/resolvers/([^/]+)/sent/([^/]+)$
    type=counter
    'help=The number of sent DNS queries of a specific type to resolve in a resolver zone.';

'angie_resolvers_responses{zone="$1",status="$2"}' $p8s_value
    path=~^/resolvers/([^/]+)/responses/([^/]+)$
    type=counter
    'help=The number of resolution results with a specific status in a resolver zone.';


'angie_http_server_zones_ssl_handshaked{zone="$1"}' $p8s_value
    path=~^/http/server_zones/([^/]+)/ssl/handshaked$
    type=counter
    'help=The total number of successful SSL handshakes in an HTTP server zone.';

'angie_http_server_zones_ssl_reuses{zone="$1"}' $p8s_value
    path=~^/http/server_zones/([^/]+)/ssl/reuses$
    type=counter
    'help=The total number of session reuses during SSL handshakes in an HTTP server zone.';

'angie_http_server_zones_ssl_timedout{zone="$1"}' $p8s_value
    path=~^/http/server_zones/([^/]+)/ssl/timedout$
    type=counter
    'help=The total number of timed-out SSL handshakes in an HTTP server zone.';

'angie_http_server_zones_ssl_failed{zone="$1"}' $p8s_value
    path=~^/http/server_zones/([^/]+)/ssl/failed$
    type=counter
    'help=The total number of failed SSL handshakes in an HTTP server zone.';


'angie_http_server_zones_requests_total{zone="$1"}' $p8s_value
    path=~^/http/server_zones/([^/]+)/requests/total$
    type=counter
    'help=The total number of client requests received in an HTTP server zone.';

'angie_http_server_zones_requests_processing{zone="$1"}' $p8s_value
    path=~^/http/server_zones/([^/]+)/requests/processing$
    type=gauge
    'help=The number of client requests currently being processed in an HTTP server zone.';

'angie_http_server_zones_requests_discarded{zone="$1"}' $p8s_value
    path=~^/http/server_zones/([^/]+)/requests/discarded$
    type=counter
    'help=The total number of client requests completed in an HTTP server zone without sending a response.';


'angie_http_server_zones_responses{zone="$1",code="$2"}' $p8s_value
    path=~^/http/server_zones/([^/]+)/responses/([^/]+)$
    type=counter
    'help=The number of responses with a specific status in an HTTP server zone.';


'angie_http_server_zones_data_received{zone="$1"}' $p8s_value
    path=~^/http/server_zones/([^/]+)/data/received$
    type=counter
    'help=The total number of bytes received from clients in an HTTP server zone.';

'angie_http_server_zones_data_sent{zone="$1"}' $p8s_value
    path=~^/http/server_zones/([^/]+)/data/sent$
    type=counter
    'help=The total number of bytes sent to clients in an HTTP server zone.';


'angie_http_location_zones_requests_total{zone="$1"}' $p8s_value
    path=~^/http/location_zones/([^/]+)/requests/total$
    type=counter
    'help=The total number of client requests in an HTTP location zone.';

'angie_http_location_zones_requests_discarded{zone="$1"}' $p8s_value
    path=~^/http/location_zones/([^/]+)/requests/discarded$
    type=counter
    'help=The total number of client requests completed in an HTTP location zone without sending a response.';


'angie_http_location_zones_responses{zone="$1",code="$2"}' $p8s_value
    path=~^/http/location_zones/([^/]+)/responses/([^/]+)$
    type=counter
    'help=The number of responses with a specific status in an HTTP location zone.';


'angie_http_location_zones_data_received{zone="$1"}' $p8s_value
    path=~^/http/location_zones/([^/]+)/data/received$
    type=counter
    'help=The total number of bytes received from clients in an HTTP location zone.';

'angie_http_location_zones_data_sent{zone="$1"}' $p8s_value
    path=~^/http/location_zones/([^/]+)/data/sent$
    type=counter
    'help=The total number of bytes sent to clients in an HTTP location zone.';


'angie_http_upstreams_peers_state{upstream="$1",peer="$2"}' $p8st_all_ups_state
    path=~^/http/upstreams/([^/]+)/peers/([^/]+)/state$
    type=gauge
    'help=The current state of an upstream peer in "HTTP": 1 - up, 2 - down, 3 - unavailable, 4 - recovering, 5 - unhealthy, 6 - checking, 7 - draining, or 8 - busy.';


'angie_http_upstreams_peers_selected_current{upstream="$1",peer="$2"}' $p8s_value
    path=~^/http/upstreams/([^/]+)/peers/([^/]+)/selected/current$
    type=gauge
    'help=The number of requests currently being processed by an upstream peer in "HTTP".';

'angie_http_upstreams_peers_selected_total{upstream="$1",peer="$2"}' $p8s_value
    path=~^/http/upstreams/([^/]+)/peers/([^/]+)/selected/total$
    type=counter
    'help=The total number of attempts to use an upstream peer in "HTTP".';


'angie_http_upstreams_peers_responses{upstream="$1",peer="$2",code="$3"}' $p8s_value
    path=~^/http/upstreams/([^/]+)/peers/([^/]+)/responses/([^/]+)$
    type=counter
    'help=The number of responses with a specific status received from an upstream peer in "HTTP".';


'angie_http_upstreams_peers_data_sent{upstream="$1",peer="$2"}' $p8s_value
    path=~^/http/upstreams/([^/]+)/peers/([^/]+)/data/sent$
    type=counter
    'help=The total number of bytes sent to an upstream peer in "HTTP".';

'angie_http_upstreams_peers_data_received{upstream="$1",peer="$2"}' $p8s_value
    path=~^/http/upstreams/([^/]+)/peers/([^/]+)/data/received$
    type=counter
    'help=The total number of bytes received from an upstream peer in "HTTP".';


'angie_http_upstreams_peers_health_fails{upstream="$1",peer="$2"}' $p8s_value
    path=~^/http/upstreams/([^/]+)/peers/([^/]+)/health/fails$
    type=counter
    'help=The total number of unsuccessful attempts to communicate with an upstream peer in "HTTP".';

'angie_http_upstreams_peers_health_unavailable{upstream="$1",peer="$2"}' $p8s_value
    path=~^/http/upstreams/([^/]+)/peers/([^/]+)/health/unavailable$
    type=counter
    'help=The number of times when an upstream peer in "HTTP" became "unavailable" due to reaching the max_fails limit.';

'angie_http_upstreams_peers_health_downtime{upstream="$1",peer="$2"}' $p8s_value
    path=~^/http/upstreams/([^/]+)/peers/([^/]+)/health/downtime$
    type=counter
    'help=The total time (in milliseconds) that an upstream peer in "HTTP" was "unavailable".';


'angie_http_upstreams_keepalive{upstream="$1"}' $p8s_value
    path=~^/http/upstreams/([^/]+)/keepalive$
    type=gauge
    'help=The number of currently cached keepalive connections for an HTTP upstream.';


'angie_http_caches_responses{zone="$1",status="$2"}' $p8s_value
    path=~^/http/caches/([^/]+)/([^/]+)/responses$
    type=counter
    'help=The total number of responses processed in an HTTP cache zone with a specific cache status.';

'angie_http_caches_bytes{zone="$1",status="$2"}' $p8s_value
    path=~^/http/caches/([^/]+)/([^/]+)/bytes$
    type=counter
    'help=The total number of bytes processed in an HTTP cache zone with a specific cache status.';

'angie_http_caches_responses_written{zone="$1",status="$2"}' $p8s_value
    path=~^/http/caches/([^/]+)/([^/]+)/responses_written$
    type=counter
    'help=The total number of responses written to an HTTP cache zone with a specific cache status.';

'angie_http_caches_bytes_written{zone="$1",status="$2"}' $p8s_value
    path=~^/http/caches/([^/]+)/([^/]+)/bytes_written$
    type=counter
    'help=The total number of bytes written to an HTTP cache zone with a specific cache status.';


'angie_http_caches_size{zone="$1"}' $p8s_value
    path=~^/http/caches/([^/]+)/size$
    type=gauge
    'help=The current size (in bytes) of cached responses in an HTTP cache zone.';


'angie_http_caches_shards_size{zone="$1",path="$2"}' $p8s_value
    path=~^/http/caches/([^/]+)/shards/([^/]+)/size$
    type=gauge
    'help=The current size (in bytes) of cached responses in a shard path of an HTTP cache zone.';


'angie_http_limit_conns{zone="$1",status="$2"}' $p8s_value
    path=~^/http/limit_conns/([^/]+)/([^/]+)$
    type=counter
    'help=The number of requests processed by an HTTP limit_conn zone with a specific result.';

'angie_http_limit_reqs{zone="$1",status="$2"}' $p8s_value
    path=~^/http/limit_reqs/([^/]+)/([^/]+)$
    type=counter
    'help=The number of requests processed by an HTTP limit_reqs zone with a specific result.';


'angie_http_acme_clients_state{client="$1"}' $p8st_acme_cert_state
    path=~^/http/acme_clients/([^/]+)/state$
    type=gauge
    'help=The current state of an ACME client: 1 - ready, 2 - requesting, 3 - disabled, or 4 - failed.';

'angie_http_acme_certs_state{client="$1"}' $p8st_acme_cli_state
    path=~^/http/acme_clients/([^/]+)/certificate$
    type=gauge
    'help=The current state of an ACME client certificate: 1 - valid, 2 - mismatch, 3 - expired, 4 - missing, or 5 - error.';


'angie_stream_server_zones_ssl_handshaked{zone="$1"}' $p8s_value
    path=~^/stream/server_zones/([^/]+)/ssl/handshaked$
    type=counter
    'help=The total number of successful SSL handshakes in a stream server zone.';

'angie_stream_server_zones_ssl_reuses{zone="$1"}' $p8s_value
    path=~^/stream/server_zones/([^/]+)/ssl/reuses$
    type=counter
    'help=The total number of session reuses during SSL handshakes in a stream server zone.';

'angie_stream_server_zones_ssl_timedout{zone="$1"}' $p8s_value
    path=~^/stream/server_zones/([^/]+)/ssl/timedout$
    type=counter
    'help=The total number of timed-out SSL handshakes in a stream server zone.';

'angie_stream_server_zones_ssl_failed{zone="$1"}' $p8s_value
    path=~^/stream/server_zones/([^/]+)/ssl/failed$
    type=counter
    'help=The total number of failed SSL handshakes in a stream server zone.';


'angie_stream_server_zones_connections_total{zone="$1"}' $p8s_value
    path=~^/stream/server_zones/([^/]+)/connections/total$
    type=counter
    'help=The total number of client connections received in a stream server zone.';

'angie_stream_server_zones_connections_processing{zone="$1"}' $p8s_value
    path=~^/stream/server_zones/([^/]+)/connections/processing$
    type=gauge
    'help=The number of client connections currently being processed in a stream server zone.';

'angie_stream_server_zones_connections_discarded{zone="$1"}' $p8s_value
    path=~^/stream/server_zones/([^/]+)/connections/discarded$
    type=counter
    'help=The total number of client connections completed in a stream server zone without establishing a session.';

'angie_stream_server_zones_connections_passed{zone="$1"}' $p8s_value
    path=~^/stream/server_zones/([^/]+)/connections/passed$
    type=counter
    'help=The total number of client connections in a stream server zone passed for handling to a different listening socket.';


'angie_stream_server_zones_sessions{zone="$1",status="$2"}' $p8s_value
    path=~^/stream/server_zones/([^/]+)/sessions/([^/]+)$
    type=counter
    'help=The number of sessions finished with a specific status in a stream server zone.';


'angie_stream_server_zones_data_received{zone="$1"}' $p8s_value
    path=~^/stream/server_zones/([^/]+)/data/received$
    type=counter
    'help=The total number of bytes received from clients in a stream server zone.';

'angie_stream_server_zones_data_sent{zone="$1"}' $p8s_value
    path=~^/stream/server_zones/([^/]+)/data/sent$
    type=counter
    'help=The total number of bytes sent to clients in a stream server zone.';


'angie_stream_upstreams_peers_state{upstream="$1",peer="$2"}' $p8st_all_ups_state
    path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/state$
    type=gauge
    'help=The current state of an upstream peer in "stream": 1 - up, 2 - down, 3 - unavailable, 4 - recovering, 7 - draining, or 8 - busy.';


'angie_stream_upstreams_peers_selected_current{upstream="$1",peer="$2"}' $p8s_value
    path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/selected/current$
    type=gauge
    'help=The number of sessions currently being processed by an upstream peer in "stream".';

'angie_stream_upstreams_peers_selected_total{upstream="$1",peer="$2"}' $p8s_value
    path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/selected/total$
    type=counter
    'help=The total number of attempts to use an upstream peer in "stream".';


'angie_stream_upstreams_peers_data_sent{upstream="$1",peer="$2"}' $p8s_value
    path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/data/sent$
    type=counter
    'help=The total number of bytes sent to an upstream peer in "stream".';

'angie_stream_upstreams_peers_data_received{upstream="$1",peer="$2"}' $p8s_value
    path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/data/received$
    type=counter
    'help=The total number of bytes received from an upstream peer in "stream".';


'angie_stream_upstreams_peers_health_fails{upstream="$1",peer="$2"}' $p8s_value
    path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/health/fails$
    type=counter
    'help=The total number of unsuccessful attempts to communicate with an upstream peer in "stream".';

'angie_stream_upstreams_peers_health_unavailable{upstream="$1",peer="$2"}' $p8s_value
    path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/health/unavailable$
    type=counter
    'help=The number of times when an upstream peer in "stream" became "unavailable" due to reaching the max_fails limit.';

'angie_stream_upstreams_peers_health_downtime{upstream="$1",peer="$2"}' $p8s_value
    path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/health/downtime$
    type=counter
    'help=The total time (in milliseconds) that an upstream peer in "stream" was "unavailable".';

}


map $p8s_value $p8st_all_ups_state {
    volatile;
    "up"           1;
    "down"         2;
    "unavailable"  3;
    "recovering"   4;
#    "unhealthy"    5;
#    "checking"     6;
    "draining"     7;
    "busy"         8;
    default        0;
}


map $p8s_value $p8st_acme_cli_state {
    volatile;
    "ready"        1;
    "requesting"   2;
    "disabled"     3;
    "failed"       4;
}


map $p8s_value $p8st_acme_cert_state {
    volatile;
    "valid"        1;
    "mismatch"     2;
    "expired"      3;
    "missing"      4;
    "error"        5;
}

```

### File Contents (Angie PRO)

```nginx

prometheus_template all {

angie_connections_accepted $p8s_value
    path=/connections/accepted
    type=counter
    'help=The total number of accepted client connections.';

angie_connections_dropped $p8s_value
    path=/connections/dropped
    type=counter
    'help=The total number of dropped client connections.';

angie_connections_active $p8s_value
    path=/connections/active
    type=gauge
    'help=The current number of active client connections.';

angie_connections_idle $p8s_value
    path=/connections/idle
    type=gauge
    'help=The current number of idle client connections.';


'angie_slabs_pages_used{zone="$1"}' $p8s_value
    path=~^/slabs/([^/]+)/pages/used$
    type=gauge
    'help=The number of currently used memory pages in a slab zone.';

'angie_slabs_pages_free{zone="$1"}' $p8s_value
    path=~^/slabs/([^/]+)/pages/free$
    type=gauge
    'help=The number of currently free memory pages in a slab zone.';


'angie_slabs_pages_slots_used{zone="$1",size="$2"}' $p8s_value
    path=~^/slabs/([^/]+)/slots/([^/]+)/used$
    type=gauge
    'help=The number of currently used memory slots of a specific size in a slab zone.';

'angie_slabs_pages_slots_free{zone="$1",size="$2"}' $p8s_value
    path=~^/slabs/([^/]+)/slots/([^/]+)/free$
    type=gauge
    'help=The number of currently free memory slots of a specific size in a slab zone.';

'angie_slabs_pages_slots_reqs{zone="$1",size="$2"}' $p8s_value
    path=~^/slabs/([^/]+)/slots/([^/]+)/reqs$
    type=counter
    'help=The total number of attempts to allocate a memory slot of a specific size in a slab zone.';

'angie_slabs_pages_slots_fails{zone="$1",size="$2"}' $p8s_value
    path=~^/slabs/([^/]+)/slots/([^/]+)/fails$
    type=counter
    'help=The number of unsuccessful attempts to allocate a memory slot of a specific size in a slab zone.';


'angie_resolvers_queries{zone="$1",type="$2"}' $p8s_value
    path=~^/resolvers/([^/]+)/queries/([^/]+)$
    type=counter
    'help=The number of queries of a specific type to resolve in a resolver zone.';

'angie_resolvers_sent{zone="$1",type="$2"}' $p8s_value
    path=~^/resolvers/([^/]+)/sent/([^/]+)$
    type=counter
    'help=The number of sent DNS queries of a specific type to resolve in a resolver zone.';

'angie_resolvers_responses{zone="$1",status="$2"}' $p8s_value
    path=~^/resolvers/([^/]+)/responses/([^/]+)$
    type=counter
    'help=The number of resolution results with a specific status in a resolver zone.';


'angie_http_server_zones_ssl_handshaked{zone="$1"}' $p8s_value
    path=~^/http/server_zones/([^/]+)/ssl/handshaked$
    type=counter
    'help=The total number of successful SSL handshakes in an HTTP server zone.';

'angie_http_server_zones_ssl_reuses{zone="$1"}' $p8s_value
    path=~^/http/server_zones/([^/]+)/ssl/reuses$
    type=counter
    'help=The total number of session reuses during SSL handshakes in an HTTP server zone.';

'angie_http_server_zones_ssl_timedout{zone="$1"}' $p8s_value
    path=~^/http/server_zones/([^/]+)/ssl/timedout$
    type=counter
    'help=The total number of timed-out SSL handshakes in an HTTP server zone.';

'angie_http_server_zones_ssl_failed{zone="$1"}' $p8s_value
    path=~^/http/server_zones/([^/]+)/ssl/failed$
    type=counter
    'help=The total number of failed SSL handshakes in an HTTP server zone.';


'angie_http_server_zones_requests_total{zone="$1"}' $p8s_value
    path=~^/http/server_zones/([^/]+)/requests/total$
    type=counter
    'help=The total number of client requests received in an HTTP server zone.';

'angie_http_server_zones_requests_processing{zone="$1"}' $p8s_value
    path=~^/http/server_zones/([^/]+)/requests/processing$
    type=gauge
    'help=The number of client requests currently being processed in an HTTP server zone.';

'angie_http_server_zones_requests_discarded{zone="$1"}' $p8s_value
    path=~^/http/server_zones/([^/]+)/requests/discarded$
    type=counter
    'help=The total number of client requests completed in an HTTP server zone without sending a response.';


'angie_http_server_zones_responses{zone="$1",code="$2"}' $p8s_value
    path=~^/http/server_zones/([^/]+)/responses/([^/]+)$
    type=counter
    'help=The number of responses with a specific status in an HTTP server zone.';


'angie_http_server_zones_data_received{zone="$1"}' $p8s_value
    path=~^/http/server_zones/([^/]+)/data/received$
    type=counter
    'help=The total number of bytes received from clients in an HTTP server zone.';

'angie_http_server_zones_data_sent{zone="$1"}' $p8s_value
    path=~^/http/server_zones/([^/]+)/data/sent$
    type=counter
    'help=The total number of bytes sent to clients in an HTTP server zone.';


'angie_http_location_zones_requests_total{zone="$1"}' $p8s_value
    path=~^/http/location_zones/([^/]+)/requests/total$
    type=counter
    'help=The total number of client requests in an HTTP location zone.';

'angie_http_location_zones_requests_discarded{zone="$1"}' $p8s_value
    path=~^/http/location_zones/([^/]+)/requests/discarded$
    type=counter
    'help=The total number of client requests completed in an HTTP location zone without sending a response.';


'angie_http_location_zones_responses{zone="$1",code="$2"}' $p8s_value
    path=~^/http/location_zones/([^/]+)/responses/([^/]+)$
    type=counter
    'help=The number of responses with a specific status in an HTTP location zone.';


'angie_http_location_zones_data_received{zone="$1"}' $p8s_value
    path=~^/http/location_zones/([^/]+)/data/received$
    type=counter
    'help=The total number of bytes received from clients in an HTTP location zone.';

'angie_http_location_zones_data_sent{zone="$1"}' $p8s_value
    path=~^/http/location_zones/([^/]+)/data/sent$
    type=counter
    'help=The total number of bytes sent to clients in an HTTP location zone.';


'angie_http_upstreams_peers_backup{upstream="$1",peer="$2"}' $p8st_all_ups_backup
    path=~^/http/upstreams/([^/]+)/peers/([^/]+)/backup$
    type=gauge
    'help=The HTTP upstream peer backup group level.';


'angie_http_upstreams_peers_state{upstream="$1",peer="$2"}' $p8st_all_ups_state
    path=~^/http/upstreams/([^/]+)/peers/([^/]+)/state$
    type=gauge
    'help=The current state of an upstream peer in "HTTP": 1 - up, 2 - down, 3 - unavailable, 4 - recovering, 5 - unhealthy, 6 - checking, 7 - draining, 8 - busy, or 9 - idle.';


'angie_http_upstreams_peers_selected_current{upstream="$1",peer="$2"}' $p8s_value
    path=~^/http/upstreams/([^/]+)/peers/([^/]+)/selected/current$
    type=gauge
    'help=The number of requests currently being processed by an upstream peer in "HTTP".';

'angie_http_upstreams_peers_selected_total{upstream="$1",peer="$2"}' $p8s_value
    path=~^/http/upstreams/([^/]+)/peers/([^/]+)/selected/total$
    type=counter
    'help=The total number of attempts to use an upstream peer in "HTTP".';


'angie_http_upstreams_peers_responses{upstream="$1",peer="$2",code="$3"}' $p8s_value
    path=~^/http/upstreams/([^/]+)/peers/([^/]+)/responses/([^/]+)$
    type=counter
    'help=The number of responses with a specific status received from an upstream peer in "HTTP".';


'angie_http_upstreams_peers_data_sent{upstream="$1",peer="$2"}' $p8s_value
    path=~^/http/upstreams/([^/]+)/peers/([^/]+)/data/sent$
    type=counter
    'help=The total number of bytes sent to an upstream peer in "HTTP".';

'angie_http_upstreams_peers_data_received{upstream="$1",peer="$2"}' $p8s_value
    path=~^/http/upstreams/([^/]+)/peers/([^/]+)/data/received$
    type=counter
    'help=The total number of bytes received from an upstream peer in "HTTP".';


'angie_http_upstreams_peers_health_fails{upstream="$1",peer="$2"}' $p8s_value
    path=~^/http/upstreams/([^/]+)/peers/([^/]+)/health/fails$
    type=counter
    'help=The total number of unsuccessful attempts to communicate with an upstream peer in "HTTP".';

'angie_http_upstreams_peers_health_unavailable{upstream="$1",peer="$2"}' $p8s_value
    path=~^/http/upstreams/([^/]+)/peers/([^/]+)/health/unavailable$
    type=counter
    'help=The number of times when an upstream peer in "HTTP" became "unavailable" due to reaching the max_fails limit.';

'angie_http_upstreams_peers_health_downtime{upstream="$1",peer="$2"}' $p8s_value
    path=~^/http/upstreams/([^/]+)/peers/([^/]+)/health/downtime$
    type=counter
    'help=The total time (in milliseconds) that an upstream peer in "HTTP" was "unavailable".';

'angie_http_upstreams_peers_health_header_time{upstream="$1",peer="$2"}' $p8s_value
    path=~^/http/upstreams/([^/]+)/peers/([^/]+)/health/header_time$
    type=gauge
    'help=Average time (in milliseconds) to receive the response headers from an upstream peer in "HTTP".';

'angie_http_upstreams_peers_health_response_time{upstream="$1",peer="$2"}' $p8s_value
    path=~^/http/upstreams/([^/]+)/peers/([^/]+)/health/response_time$
    type=gauge
    'help=Average time (in milliseconds) to receive the complete response from an upstream peer in "HTTP".';

'angie_http_upstreams_peers_health_probes_count{upstream="$1",peer="$2"}' $p8s_value
    path=~^/http/upstreams/([^/]+)/peers/([^/]+)/health/probes/count$
    type=counter
    'help=The total number of probes for this peer.';

'angie_http_upstreams_peers_health_probes_fails{upstream="$1",peer="$2"}' $p8s_value
    path=~^/http/upstreams/([^/]+)/peers/([^/]+)/health/probes/fails$
    type=counter
    'help=The total number of failed probes for this peer.';

'angie_http_upstreams_peers_balance_feedback{upstream="$1",peer="$2"}' $p8s_value
    path=~^/http/upstreams/([^/]+)/peers/([^/]+)/feedback$
    type=gauge
    'help=The feedback balancer indicator, average value.';

'angie_http_upstreams_peers_balance_bandwidth{upstream="$1",peer="$2"}' $p8s_value
    path=~^/http/upstreams/([^/]+)/peers/([^/]+)/bandwidth$
    type=gauge
    'help=The least_bandwidth balancer indicator, average value.';


'angie_http_upstreams_keepalive{upstream="$1"}' $p8s_value
    path=~^/http/upstreams/([^/]+)/keepalive$
    type=gauge
    'help=The number of currently cached keepalive connections for an HTTP upstream.';


'angie_http_upstreams_backup_switch_active{upstream="$1"}' $p8s_value
    path=~^/http/upstreams/([^/]+)/backup_switch/active$
    type=gauge
    'help=The currently active HTTP upstream servers backup group level.';


'angie_http_upstreams_queue_queued{upstream="$1"}' $p8s_value
    path=~^/http/upstreams/([^/]+)/queue/queued$
    type=counter
    'help=The total number of queued requests for an HTTP upstream.';

'angie_http_upstreams_queue_waiting{upstream="$1"}' $p8s_value
    path=~^/http/upstreams/([^/]+)/queue/waiting$
    type=gauge
    'help=The number of requests currently waiting in an HTTP upstream queue.';

'angie_http_upstreams_queue_dropped{upstream="$1"}' $p8s_value
    path=~^/http/upstreams/([^/]+)/queue/dropped$
    type=counter
    'help=The total number of requests dropped from an HTTP upstream queue because the client had prematurely closed the connection.';

'angie_http_upstreams_queue_timedout{upstream="$1"}' $p8s_value
    path=~^/http/upstreams/([^/]+)/queue/timedout$
    type=counter
    'help=The total number of requests timed out from an HTTP upstream queue.';

'angie_http_upstreams_queue_overflows{upstream="$1"}' $p8s_value
    path=~^/http/upstreams/([^/]+)/queue/overflows$
    type=counter
    'help=The total number of requests rejected by an HTTP upstream queue because the size limit had been reached.';


'angie_http_caches_responses{zone="$1",status="$2"}' $p8s_value
    path=~^/http/caches/([^/]+)/([^/]+)/responses$
    type=counter
    'help=The total number of responses processed in an HTTP cache zone with a specific cache status.';

'angie_http_caches_bytes{zone="$1",status="$2"}' $p8s_value
    path=~^/http/caches/([^/]+)/([^/]+)/bytes$
    type=counter
    'help=The total number of bytes processed in an HTTP cache zone with a specific cache status.';

'angie_http_caches_responses_written{zone="$1",status="$2"}' $p8s_value
    path=~^/http/caches/([^/]+)/([^/]+)/responses_written$
    type=counter
    'help=The total number of responses written to an HTTP cache zone with a specific cache status.';

'angie_http_caches_bytes_written{zone="$1",status="$2"}' $p8s_value
    path=~^/http/caches/([^/]+)/([^/]+)/bytes_written$
    type=counter
    'help=The total number of bytes written to an HTTP cache zone with a specific cache status.';


'angie_http_caches_size{zone="$1"}' $p8s_value
    path=~^/http/caches/([^/]+)/size$
    type=gauge
    'help=The current size (in bytes) of cached responses in an HTTP cache zone.';


'angie_http_caches_shards_size{zone="$1",path="$2"}' $p8s_value
    path=~^/http/caches/([^/]+)/shards/([^/]+)/size$
    type=gauge
    'help=The current size (in bytes) of cached responses in a shard path of an HTTP cache zone.';


'angie_http_limit_conns{zone="$1",status="$2"}' $p8s_value
    path=~^/http/limit_conns/([^/]+)/([^/]+)$
    type=counter
    'help=The number of requests processed by an HTTP limit_conn zone with a specific result.';

'angie_http_limit_reqs{zone="$1",status="$2"}' $p8s_value
    path=~^/http/limit_reqs/([^/]+)/([^/]+)$
    type=counter
    'help=The number of requests processed by an HTTP limit_reqs zone with a specific result.';


'angie_http_acme_clients_state{client="$1"}' $p8st_acme_cert_state
    path=~^/http/acme_clients/([^/]+)/state$
    type=gauge
    'help=The current state of an ACME client: 1 - ready, 2 - requesting, 3 - disabled, or 4 - failed.';

'angie_http_acme_certs_state{client="$1"}' $p8st_acme_cli_state
    path=~^/http/acme_clients/([^/]+)/certificate$
    type=gauge
    'help=The current state of an ACME client certificate: 1 - valid, 2 - mismatch, 3 - expired, 4 - missing, or 5 - error.';


'angie_stream_server_zones_ssl_handshaked{zone="$1"}' $p8s_value
    path=~^/stream/server_zones/([^/]+)/ssl/handshaked$
    type=counter
    'help=The total number of successful SSL handshakes in a stream server zone.';

'angie_stream_server_zones_ssl_reuses{zone="$1"}' $p8s_value
    path=~^/stream/server_zones/([^/]+)/ssl/reuses$
    type=counter
    'help=The total number of session reuses during SSL handshakes in a stream server zone.';

'angie_stream_server_zones_ssl_timedout{zone="$1"}' $p8s_value
    path=~^/stream/server_zones/([^/]+)/ssl/timedout$
    type=counter
    'help=The total number of timed-out SSL handshakes in a stream server zone.';

'angie_stream_server_zones_ssl_failed{zone="$1"}' $p8s_value
    path=~^/stream/server_zones/([^/]+)/ssl/failed$
    type=counter
    'help=The total number of failed SSL handshakes in a stream server zone.';


'angie_stream_server_zones_connections_total{zone="$1"}' $p8s_value
    path=~^/stream/server_zones/([^/]+)/connections/total$
    type=counter
    'help=The total number of client connections received in a stream server zone.';

'angie_stream_server_zones_connections_processing{zone="$1"}' $p8s_value
    path=~^/stream/server_zones/([^/]+)/connections/processing$
    type=gauge
    'help=The number of client connections currently being processed in a stream server zone.';

'angie_stream_server_zones_connections_discarded{zone="$1"}' $p8s_value
    path=~^/stream/server_zones/([^/]+)/connections/discarded$
    type=counter
    'help=The total number of client connections completed in a stream server zone without establishing a session.';

'angie_stream_server_zones_connections_passed{zone="$1"}' $p8s_value
    path=~^/stream/server_zones/([^/]+)/connections/passed$
    type=counter
    'help=The total number of client connections in a stream server zone passed for handling to a different listening socket.';


'angie_stream_server_zones_sessions{zone="$1",status="$2"}' $p8s_value
    path=~^/stream/server_zones/([^/]+)/sessions/([^/]+)$
    type=counter
    'help=The number of sessions finished with a specific status in a stream server zone.';


'angie_stream_server_zones_data_received{zone="$1"}' $p8s_value
    path=~^/stream/server_zones/([^/]+)/data/received$
    type=counter
    'help=The total number of bytes received from clients in a stream server zone.';

'angie_stream_server_zones_data_sent{zone="$1"}' $p8s_value
    path=~^/stream/server_zones/([^/]+)/data/sent$
    type=counter
    'help=The total number of bytes sent to clients in a stream server zone.';


'angie_stream_upstreams_peers_backup{upstream="$1",peer="$2"}' $p8st_all_ups_backup
    path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/backup$
    type=gauge
    'help=The "stream" upstream peer backup group level.';


'angie_stream_upstreams_peers_state{upstream="$1",peer="$2"}' $p8st_all_ups_state
    path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/state$
    type=gauge
    'help=The current state of an upstream peer in "stream": 1 - up, 2 - down, 3 - unavailable, 4 - recovering, 5 - unhealthy, 6 - checking, 7 - draining, 8 - busy, or 9 - idle.';


'angie_stream_upstreams_peers_selected_current{upstream="$1",peer="$2"}' $p8s_value
    path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/selected/current$
    type=gauge
    'help=The number of sessions currently being processed by an upstream peer in "stream".';

'angie_stream_upstreams_peers_selected_total{upstream="$1",peer="$2"}' $p8s_value
    path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/selected/total$
    type=counter
    'help=The total number of attempts to use an upstream peer in "stream".';


'angie_stream_upstreams_peers_data_sent{upstream="$1",peer="$2"}' $p8s_value
    path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/data/sent$
    type=counter
    'help=The total number of bytes sent to an upstream peer in "stream".';

'angie_stream_upstreams_peers_data_received{upstream="$1",peer="$2"}' $p8s_value
    path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/data/received$
    type=counter
    'help=The total number of bytes received from an upstream peer in "stream".';

'angie_stream_upstreams_peers_data_pkt_sent{upstream="$1",peer="$2"}' $p8s_value
    path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/data/pkt_sent$
    type=counter
    'help=The total number of packets sent to an upstream peer in "stream".';

'angie_stream_upstreams_peers_data_pkt_received{upstream="$1",peer="$2"}' $p8s_value
    path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/data/pkt_received$
    type=counter
    'help=The total number of packets received from an upstream peer in "stream".';


'angie_stream_upstreams_peers_health_fails{upstream="$1",peer="$2"}' $p8s_value
    path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/health/fails$
    type=counter
    'help=The total number of unsuccessful attempts to communicate with an upstream peer in "stream".';

'angie_stream_upstreams_peers_health_unavailable{upstream="$1",peer="$2"}' $p8s_value
    path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/health/unavailable$
    type=counter
    'help=The number of times when an upstream peer in "stream" became "unavailable" due to reaching the max_fails limit.';

'angie_stream_upstreams_peers_health_downtime{upstream="$1",peer="$2"}' $p8s_value
    path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/health/downtime$
    type=counter
    'help=The total time (in milliseconds) that an upstream peer in "stream" was "unavailable".';

'angie_stream_upstreams_peers_health_connect_time{upstream="$1",peer="$2"}' $p8s_value
    path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/health/connect_time$
    type=gauge
    'help=Average time (in milliseconds) to connect to an upstream peer in "stream".';

'angie_stream_upstreams_peers_health_first_byte_time{upstream="$1",peer="$2"}' $p8s_value
    path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/health/first_byte_time$
    type=gauge
    'help=Average time (in milliseconds) to receive the first byte from an upstream peer in "stream".';

'angie_stream_upstreams_peers_health_last_byte_time{upstream="$1",peer="$2"}' $p8s_value
    path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/health/last_byte_time$
    type=gauge
    'help=Average time (in milliseconds) of the whole communication session with an upstream peer in "stream".';


'angie_stream_upstreams_peers_health_probes_count{upstream="$1",peer="$2"}' $p8s_value
    path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/health/probes/count$
    type=counter
    'help=The total number of probes for this peer.';

'angie_stream_upstreams_peers_health_probes_fails{upstream="$1",peer="$2"}' $p8s_value
    path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/health/probes/fails$
    type=counter
    'help=The total number of failed probes for this peer.';

'angie_stream_upstreams_peers_balance_feedback{upstream="$1",peer="$2"}' $p8s_value
    path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/feedback$
    type=gauge
    'help=The feedback balancer indicator, average value.';

'angie_stream_upstreams_peers_balance_bandwidth{upstream="$1",peer="$2"}' $p8s_value
    path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/bandwidth$
    type=gauge
    'help=The least_bandwidth balancer indicator, average value.';

'angie_stream_upstreams_peers_balance_packets{upstream="$1",peer="$2"}' $p8s_value
    path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/packets$
    type=gauge
    'help=The least_packets balancer indicator, average value.';


'angie_stream_upstreams_backup_switch_active{upstream="$1"}' $p8s_value
    path=~^/stream/upstreams/([^/]+)/backup_switch/active$
    type=gauge
    'help=The currently active "stream" upstream servers backup group level.';
}


map $p8s_value $p8st_all_ups_state {
    volatile;
    "up"           1;
    "down"         2;
    "unavailable"  3;
    "recovering"   4;
    "unhealthy"    5;
    "checking"     6;
    "draining"     7;
    "busy"         8;
    "idle"         9;
    default        0;
}

map $p8s_value $p8st_all_ups_backup {
    volatile;
    "false"        0;
    "true"         1;
    default        $p8s_value;
}


map $p8s_value $p8st_acme_cli_state {
    volatile;
    "ready"        1;
    "requesting"   2;
    "disabled"     3;
    "failed"       4;
}

map $p8s_value $p8st_acme_cert_state {
    volatile;
    "valid"        1;
    "mismatch"     2;
    "expired"      3;
    "missing"      4;
    "error"        5;
}

```

Usage:

```nginx
http {

    include prometheus_all.conf;

    # ...

    server {

        listen 80;

        location =/p8s {
            prometheus all;
        }

        # ...

    }
}
```

```console
$ curl localhost/p8s

    # Angie Prometheus template "all"
    ...
```



## Directives





### prometheus

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `prometheus` template_name;   |
|------------------------------------------------------------------------------------------|-------------------------------|
| Default                                                                                  | —                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | location                      |

Specifies a template handler for the `location` context,
defined by the [prometheus_template](#prometheus-template) directive.
When requested, this `location` calculates and returns the template metrics
in Prometheus format.

```nginx
location =/p8s {
    prometheus custom;
}
```

```console
$ curl localhost/p8s

    # Angie Prometheus template "custom"
    ...
```





### prometheus_template

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `prometheus_template` template_name { ... }   |
|------------------------------------------------------------------------------------------|-----------------------------------------------|
| Default                                                                                  | —                                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                                          |

Defines a named template of metrics collected and exported by Angie,
for use with the [prometheus](#id1) directive.

#### NOTE
Angie also includes a ready-made [all](#prometheus-all) template
that contains a set of the most commonly used metrics.

Can contain any number of metric definitions,
each having the following structure:
  [`path=`] [`type=`] [`help=`].

| `metric_name`   | Sets the metric name
under which it will be added in Prometheus format to the response.
Can contain an optional labels section (` *...*`), for example:

```none
http_requests_total{method="$1",code="$2"}
```

Label values can use Angie [variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables);
if match_string is defined as a regular expression,
you can also use capture groups defined in that expression.
Such variables and groups are evaluated when obtaining the metric value,
which is set by variable.   |
|-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `variable`      | Sets the name of the variable that will be evaluated and added
as the metric value to the response.
If the variable doesn't exist or the evaluation result is empty (`""`),
the metric is not added.                                                                                                                                                                                                                                                                                                                                                                                                  |

The metric is calculated with the value set by variable;
upon successful evaluation, the metric is added to the response, for example:

```nginx
'angie_time{version="$angie_version"}' $msec;
```

```console
$ curl localhost/p8s

    angie_time{version="1.12.1"} 1695119820.562
```

| `path=match_string`   | Is matched against all endpoint paths of metrics in the
[/status](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#metrics)
API subtree of Angie,
allowing multiple instances of the metric to be added to the response at once.   |
|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

During matching, paths are taken with the leading slash but without the trailing one,
for example `/angie/generation`; matching is case-insensitive.
There are two matching methods:

| `path=exact_match`         | Checked by character-by-character comparison.                                                                 |
|----------------------------|---------------------------------------------------------------------------------------------------------------|
| `path=~regular_expression` | Checked using the PCRE library; can define capture groups
for use in the labels of the metric_name field. |

If match_string matches any path,
the value of the Angie metric at that path is stored in the
[$p8s_value](#v-p8s-value) variable,
which can be used in the variable field when `path=` is specified.

If match_string ends with a trailing slash, the metric value is the number of
items in the corresponding list or object. For example:

```nginx
'angie_http_server_zones_count' $p8s_value
    path=/http/server_zones/;
```

In the case of regular expressions, there can be multiple matching paths;
the metric is added to the response for *each* match.
Combined with capture groups, this allows obtaining a series of metrics
with the same name and different labels, for example:

```nginx
'angie_slabs_slots_free{zone="$1",size="$2"}' $p8s_value
    path=~^/slabs/([^/]+)/slots/([^/]+)/free$;
```

This definition adds metrics for all zones and all sizes
that currently exist in the configuration:

```none
angie_slabs_slots_free{zone="one",size="8"} 502
angie_slabs_slots_free{zone="one",size="16"} 249
angie_slabs_slots_free{zone="one",size="32"} 122
angie_slabs_slots_free{zone="one",size="128"} 22
angie_slabs_slots_free{zone="one",size="512"} 4
angie_slabs_slots_free{zone="two",size="8"} 311
...
```

If there are no matches (with any matching method),
the metric is not added.

#### NOTE
The `path=` parameter is available only
when Angie is built with the [API](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#http-api) module.

| `type=type`, `help=help`   | Set the metric's type and help string, respectively, in the
[Prometheus format](https://prometheus.io/docs/instrumenting/exposition_formats/#comments-help-text-and-type-information),
which are added with the metric to the response without changes or validation.   |
|----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|



## Built-in Variables

The `http_prometheus` module has a built-in variable
that receives its value when matching metric paths from the
[/status](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#metrics)
section of the Angie API
with the match_string parameter of metrics defined by the
[prometheus_template](#prometheus-template) directive.



### `$p8s_value`

If the match_string of a metric defined in [prometheus_template](#prometheus-template)
matches any path,
the value of the Angie metric located at that path
is stored in the `$p8s_value` variable.
It is intended for use in the variable field in metric definitions
that are calculated based on the `path=` parameter.

The values of Angie metrics stored in the `$p8s_value` variable
do not always meet the requirements of the Prometheus format.
In such cases, you can use the [map](https://en.angie.software//angie/docs/configuration/modules/http/http_map.md#id1) directive,
for example to convert strings to numbers:

```nginx
map $p8s_value $ups_state_n {
    up           0;
    unavailable  1;
    down         2;
    default      3;
}

prometheus_template main {
    'angie_http_upstreams_state{upstream="$1",peer="$2"}' $ups_state_n
        path=~^/http/upstreams/([^/]+)/peers/([^/]+)/state$;
}
```

If the Angie metric has a boolean value, that is `true` or `false`,
the variable receives the value `"1"` or `"0"` respectively;
if the metric value is `null`, the variable will be `"(null)"`.
For dates, the integer UNIX epoch format is used.


# https://en.angie.software/angie/docs/configuration/modules/http/http_proxy.md







# Proxy

Allows passing requests to another (proxied) server.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by
default; it can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-http_proxy_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
location / {
    proxy_pass       http://localhost:8000;
    proxy_set_header Host      $host;
    proxy_set_header X-Real-IP $remote_addr;

    proxy_cache       cache_zone;
    proxy_cache_valid 200 302 10m;
    proxy_cache_valid 404      1m;
}
```



## Directives





### proxy_bind

#### Versionchanged
Changed in version 1.12.0: PRO

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_bind` address [`transparent`] | `off`;   |
|------------------------------------------------------------------------------------------|-------------------------------------------------|
| Default                                                                                  | —                                               |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                          |

Makes outgoing connections to a proxied server originate from the specified local IP address with an optional port. Parameter value can contain [variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables). The special value `off` cancels the effect of the proxy_bind directive inherited from the previous configuration level, which allows the system to auto-assign the local IP address and port.

By default, this value is evaluated once when the request is initialized, before
a proxied server is selected. In Angie PRO, evaluation happens after each
proxied server selection (including retries), so the bind address can depend on
the selected server; for example, via the `$upstream_current_addr`
variable. If the evaluated value is empty, no binding is made.

The `transparent` parameter allows outgoing connections to a proxied
server originate from a non-local IP address, for example, from a real IP
address of a client:

```nginx
proxy_bind $remote_addr transparent;
```

In order for this parameter to work, it is usually necessary to run Angie worker processes with the [superuser](https://en.angie.software//angie/docs/configuration/modules/core.md#user) privileges. On Linux it is not required as if the `transparent` parameter is specified, worker processes inherit the CAP_NET_RAW capability from the master process.

#### NOTE
It is necessary to configure kernel routing table to intercept network traffic from the proxied server.





### proxy_buffer_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_buffer_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `proxy_buffer_size 4k|8k;`                                                                                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                             |

Sets the size of the buffer used for reading the first part of the response received from the proxied server. This part usually contains a small response header. By default, the buffer size is equal to one memory page. This is either 4K or 8K, depending on a platform. It can be made smaller, however.





### proxy_buffering

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_buffering` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-----------------------------------|
| Default                                                                                  | `proxy_buffering on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location            |

Enables or disables buffering of responses from the proxied server.

| `on`   | Angie receives a response from the proxied server as soon as possible, saving it into the buffers set by the [proxy_buffer_size](#proxy-buffer-size) and [proxy_buffers](#proxy-buffers) directives. Sending to the client is performed in parallel: filled buffers are passed for sending, but their total size is limited by [proxy_busy_buffers_size](#proxy-busy-buffers-size). If a buffer is not completely filled, it is not passed for sending unless it contains the last part of the response. Therefore, buffered reading is not suitable when you need immediate delivery of every few bytes. If the whole response does not fit into memory, a part of it can be saved to a [temporary file](#proxy-temp-path) on the disk. Writing to temporary files is controlled by the [proxy_max_temp_file_size](#proxy-max-temp-file-size) and [proxy_temp_file_write_size](#proxy-temp-file-write-size) directives.   |
|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off`  | The response is passed to a client immediately as it is received. Angie works in a "read — send" loop and does not wait for the buffer to fill completely: for example, 10 bytes read from a 4K buffer are sent right away. At the same time, if the entire response fits into the buffer, Angie can read it in full. The maximum size of the data that Angie can receive from the server at a time is set by the [proxy_buffer_size](#proxy-buffer-size) directive. With `off`, Angie does not cache responses and [proxy_limit_rate](#proxy-limit-rate) does not work.                                                                                                                                                                                                                                                                                                                                                   |

Buffering can also be enabled or disabled by passing "yes" or "no" in the `X-Accel-Buffering` response header field. This capability can be disabled using the [proxy_ignore_headers](#proxy-ignore-headers) directive.





### proxy_buffers

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_buffers` number [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `proxy_buffers 8 4k | 8k;`                                                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                |

Sets the number and size of the buffers used for reading a response from the proxied server, for a single connection.

By default, the buffer size is equal to one memory page. This is either 4K or 8K, depending on a platform.





### proxy_busy_buffers_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_busy_buffers_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `proxy_busy_buffers_size 8k | 16k;`                                                                                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                   |

When [buffering](#proxy-buffering) of responses from the proxied server is enabled, limits the total size of buffers that can be busy sending a response to the client while the response is not yet fully read. In the meantime, the rest of the buffers can be used for reading the response and, if needed, buffering part of the response to a temporary file.

By default, size is limited by the size of two buffers set by the [proxy_buffer_size](#proxy-buffer-size) and [proxy_buffers](#proxy-buffers) directives.





### proxy_cache

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_cache` zone | `off` [`path=`path];   |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| Default                                                                                  | `proxy_cache off;`                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                      |

Defines a shared memory zone used for caching.
The same zone can be used in several places.
Parameter value can contain variables.

| `off`   | disables caching inherited from the previous configuration level.   |
|---------|---------------------------------------------------------------------|

In Angie PRO, you can specify multiple [proxy_cache_path](#proxy-cache-path) directives that
use the same `keys_zone` value to enable cache sharding. When doing so,
you should set the `path` parameter of the [proxy_cache](#proxy-cache) directive
that uses this `keys_zone` value:

| `path=`path   | The value is evaluated at the time of *caching* the response from the backend
and is expected to use variables, including those containing
information from the response.

If the response is taken from the cache, the path is not reevaluated;
thus, a cached response retains its original path
until it is removed from the cache.   |
|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

This allows selecting the needed cache path by applying [map](https://en.angie.software//angie/docs/configuration/modules/http/http_map.md#id1) directives or
scripts to responses from the backend. Example for `Content-Type`:

```nginx
proxy_cache_path /cache/one keys_zone=zone:10m;
proxy_cache_path /cache/two keys_zone=zone;

map $upstream_http_content_type $cache {
   ~^text/  one;
   default  two;
}

server {
   ...
   location / {
       proxy_pass http://backend;
       proxy_cache zone path=/cache/$cache;
       proxy_cache_valid 200 10m;
   }
}
```

Here there are two cache paths and a variable mapping to distinguish between them.
If `Content-Type` starts with `text/`, the first path will be chosen,
otherwise the second.

#### NOTE
When using [proxy_cache](#proxy-cache),
you typically need to also set the [proxy_cache_valid](#proxy-cache-valid) directive
to explicitly specify the caching time for responses.
If it's not set, Angie doesn't use default values
but determines the response caching time
based on HTTP response headers from the server in the following priority order:

1. The `X-Accel-Expires` header (highest priority).
2. The `Cache-Control` header
   with `max-age` or `s-maxage` parameters.
3. The `Expires` header.

If none of these headers contain valid values or are not present at all,
the response will not be cached because its expiration time cannot be determined.





### proxy_cache_background_update

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_cache_background_update` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-------------------------------------------------|
| Default                                                                                  | `proxy_cache_background_update off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                          |

Allows starting a background subrequest to update an expired cache item, while a stale cached response is returned to the client.

#### WARNING
The use of a stale cached response while it's being updated must be [allowed](#proxy-cache-use-stale-updating).





### proxy_cache_bypass

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_cache_bypass` ...;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| Default                                                                                  | —                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location      |

Defines conditions under which the response will not be taken from cache. If at least one value of the string parameters is not empty and is not equal to "0", then the response will not be taken from cache:

```nginx
proxy_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
proxy_cache_bypass $http_pragma    $http_authorization;
```

Parameter values can contain variables.

Can be used together with the [proxy_no_cache](#proxy-no-cache) directive.





### proxy_cache_convert_head

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_cache_convert_head` `on` | `off`;   |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| Default                                                                                  | `proxy_cache_convert_head on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                     |

Enables or disables the conversion of the "HEAD" method to "GET" for caching. If conversion is disabled, the [cache key](#proxy-cache-key) must include the [$request_method](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-request-method).





### proxy_cache_key

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_cache_key` string;                         |
|------------------------------------------------------------------------------------------|---------------------------------------------------|
| Default                                                                                  | `proxy_cache_key $scheme$proxy_host$request_uri;` |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                            |

Defines a key for caching. The key can contain variables. For example,

```nginx
proxy_cache_key "$host$request_uri $cookie_user";
```

By default, the directive's value is close to the string

```nginx
proxy_cache_key $scheme$proxy_host$uri$is_args$args;
```





### proxy_cache_lock

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_cache_lock` `on` | `off`;   |
|------------------------------------------------------------------------------------------|------------------------------------|
| Default                                                                                  | `proxy_cache_lock off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location             |

When enabled, only one request at a time will be allowed to populate a new cache element identified according to the [proxy_cache_key](#proxy-cache-key) directive by passing a request to the proxied server. Other requests for the same cache element will either wait for a response to appear in cache or for the cache lock for this element to be released, up to the time set by the [proxy_cache_lock_timeout](#proxy-cache-lock-timeout) directive.





### proxy_cache_lock_age

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_cache_lock_age` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `proxy_cache_lock_age 5s;`                                                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                |

If the last request passed to the proxied server for populating a new cache element has not completed for the specified time, one more request may be passed to the proxied server.





### proxy_cache_lock_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_cache_lock_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `proxy_cache_lock_timeout 5s;`                                                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                    |

Sets a timeout for [proxy_cache_lock](#proxy-cache-lock). When the time expires, the request will be passed to the proxied server, however, the response will not be cached.





### proxy_cache_max_range_offset

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_cache_max_range_offset` number;   |
|------------------------------------------------------------------------------------------|------------------------------------------|
| Default                                                                                  | —                                        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                   |

Sets an offset in bytes for byte-range requests. If the range is beyond the specified offset, the range request will be passed to the proxied server and the response will not be cached.





### proxy_cache_methods

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_cache_methods` `GET` | `HEAD` | `POST` ...;   |
|------------------------------------------------------------------------------------------|------------------------------------------------------|
| Default                                                                                  | `proxy_cache_methods GET HEAD;`                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                               |

If the client request method is listed in this directive, then the response will be cached. "GET" and "HEAD" methods are always added to the list, but it is recommended to specify them explicitly. See also the [proxy_no_cache](#proxy-no-cache) directive.





### proxy_cache_min_uses

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_cache_min_uses` number;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | `proxy_cache_min_uses 1;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location           |

Sets the number of requests after which the response will be cached.

#### WARNING
Cache metadata is stored in shared memory. Manually deleting cache files does
not reset the counters and may lead to unpredictable behavior. For a complete
reset, stop the server, delete the cache directory, and start again.

#### NOTE
Third-party cache purge modules (for example, [Cache Purge](https://en.angie.software//angie/docs/configuration/modules/external-modules/cache-purge.md#external-cache-purge)) only delete
files but do not reset the proxy_cache_min_uses counter. The directive
is intended to protect the cache from pollution by infrequent requests, and resetting
the counter on purge may negatively affect performance.





### proxy_cache_path

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_cache_path` path [`levels=`levels] [`use_temp_path=``on` | `off`] `keys_zone=`name:size[:`file=`file] [`inactive=`time] [`max_size=`size] [`min_free=`size] [`manager_files=`number] [`manager_sleep=`time] [`manager_threshold=`time] [`loader_files=`number] [`loader_sleep=`time] [`loader_threshold=`time];   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | —                                                                                                                                                                                                                                                                                                                        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                                                                                                                                                                                                                                                                                                                     |

Sets the path and other parameters of a cache. Cache data are stored in files. The file name in a cache is a result of applying the MD5 function to the [cache key](#proxy-cache-key).

| `levels`   | defines hierarchy levels of a cache: from 1 to 3, each level accepts values 1 or 2.   |
|------------|---------------------------------------------------------------------------------------|

For example, in the following configuration:

```nginx
proxy_cache_path /data/angie/cache levels=1:2 keys_zone=one:10m;
```

file names in a cache will look like this:

```nginx
/data/angie/cache/c/29/b7f54b2df7773722d382f4809d65029c
```

A cached response is first written to a temporary file, and then the file is renamed. Temporary files and the cache can be put on different file systems. However, be aware that in this case a file is copied across two file systems instead of the cheap renaming operation. It is thus recommended that for any given location both cache and a directory holding temporary files are put on the same file system.

| `use_temp_path=on` | `off`   | determines the directory to be used for temporary files                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
|------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `on`                         | If the parameter is not specified or set to `on`, the directory specified by the [proxy_temp_path](#proxy-temp-path) directive for the given location will be used                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `off`                        | temporary files will be placed directly in the cache directory                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `keys_zone`                  | Sets the name and size of the shared memory zone for storing all active keys and information about data. Cache metadata is stored in shared memory.

The zone size is specified in bytes and must be at least two system
memory pages. The `k` and `m` suffixes are also accepted;
unlike `max_size`, this parameter does not accept `g`.

A zone of 1 megabyte is sufficient to store about 8000 keys.

When an optional file is specified with `keys_zone`,
Angie dumps the contents of this zone to disk
when the main process terminates
and attempts to restore it at the same memory address
on the next [startup](https://en.angie.software//angie/docs/configuration/runtime.md#runtime)
or after [binary upgrade](https://en.angie.software//angie/docs/configuration/runtime.md#service-upgrade),
to ensure more reliable data persistence
and reduce cache loading time.

If the zone cannot be restored due to a change in its size,
binary version incompatibility, or other reasons,
Angie will log a warning (`failed to restore zone at address`)
and will not use the zone restoration mechanism.
Instead, the incompatible file will be renamed to `.old`;
you can either delete it,
or restore its name and revert Angie to the configuration and version
in which this file was originally created.

#### WARNING
Make sure the path to the file is specified correctly
and has the necessary access permissions for Angie to use,
and is protected from unauthorized access;
relative paths are based on the [prefix](https://en.angie.software//angie/docs/installation/sourcebuild.md#paths). |
| `inactive`                   | If cached data is not accessed within the time set by this parameter, it is removed, regardless of its freshness; each access resets this timer. This differs from the size-based eviction performed by the **cache manager** described below: inactivity-based removal applies even when the cache is below `max_size`, and it ignores the validity periods configured with [proxy_cache_valid](#proxy-cache-valid).

By default, `inactive` is 10 minutes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

#### NOTE
In Angie PRO, multiple proxy_cache_path directives can be specified with the same
`keys_zone` value. The shared memory zone size can only be
specified in the first one. Selection between directives will be
made based on the `path` parameter of the corresponding
[proxy_cache](#proxy-cache) directive.

A special **cache manager** process monitors the maximum cache size and the minimum amount of free space on the filesystem with the cache, and removes the least recently used data when the maximum cache size is exceeded or there is insufficient free space. Data removal occurs in iterations.

| `max_size`          | maximum threshold value for cache size

The value is specified in bytes; the `k`, `m`, and
`g` suffixes are also accepted.
By default, the cache size is not limited.                                                                                                                                                                                                              |
|---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `min_free`          | minimum threshold value for free space on the file system with the cache

The value is specified in the same units as `max_size`.
The default value `0` disables free space monitoring.

On platforms that do not support querying file system statistics,
the parameter is ignored, and Angie logs the warning
`min_free is not supported on this platform, ignored`. |
| `manager_files`     | maximum number of cache items to be removed in one iteration

By default: `100`.                                                                                                                                                                                                                                                                                                           |
| `manager_threshold` | limits the duration of one iteration

By default: `200` milliseconds.                                                                                                                                                                                                                                                                                                                      |
| `manager_sleep`     | configures a pause between iterations

By default: `50` milliseconds.                                                                                                                                                                                                                                                                                                                      |

One minute after Angie starts, a special **cache loader** process is activated.
It scans the filesystem for previously cached data
and loads this information into the cache zone.
This process works iteratively;
each iteration processes a limited number of items specified by the `loader_files` parameter,
ensures it doesn't exceed `loader_threshold`,
then takes a short pause defined by `loader_sleep`
before moving to the next batch.
Iterations continue
until the loader has processed all existing cache entries on disk:

| `loader_files`     | maximum number of cache items to load in one iteration

By default: `100`   |
|--------------------|-------------------------------------------------------------------------------------|
| `loader_threshold` | limits the duration of one iteration

By default: `200` milliseconds        |
| `loader_sleep`     | configures a pause between iterations

By default: `50` milliseconds        |

#### NOTE
Specifying the file for the `keys_zone` parameter
does not affect the cache loader operation.





### proxy_cache_revalidate

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_cache_revalidate` `on` | `off`;   |
|------------------------------------------------------------------------------------------|------------------------------------------|
| Default                                                                                  | `proxy_cache_revalidate off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                   |

Enables revalidation of expired cache items using conditional requests with the `If-Modified-Since` and `If-None-Match` header fields.





### proxy_cache_use_stale

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_cache_use_stale` `error` | `timeout` | `invalid_header` | `updating` | `http_500` | `http_502` | `http_503` | `http_504` | `http_403` | `http_404` | `http_429` | `off` ...;   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `proxy_cache_use_stale off;`                                                                                                                                                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                                                                                |

Determines in which cases a stale cached response can be used. The directive parameters match those of the [proxy_next_upstream](#proxy-next-upstream) directive.

| `error`    | permits using a stale cached response if a proxied server to process a request cannot be selected.                                                                                        |
|------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `updating` | additional parameter, permits using a stale cached response if it is currently being updated. This allows minimizing the number of accesses to proxied servers when updating cached data. |

Using a stale cached response can also be enabled directly in the response header for a specified number of seconds after the response became stale:

* The [stale-while-revalidate](https://datatracker.ietf.org/doc/html/rfc5861#section-3) extension of the `Cache-Control` header field permits using a stale cached response if it is currently being updated.
* The [stale-if-error](https://datatracker.ietf.org/doc/html/rfc5861#section-4) extension of the `Cache-Control` header field permits using a stale cached response in case of an error.

#### NOTE
This has lower priority than using the directive parameters.

To minimize the number of accesses to proxied servers when populating a new cache element, the [proxy_cache_lock](#proxy-cache-lock) directive can be used.





### proxy_cache_valid

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_cache_valid` [code ...] [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | —                                                                                                                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                        |

Sets caching time for different response codes. For example, the directives

```nginx
proxy_cache_valid 200 302 10m;
proxy_cache_valid 404      1m;
```

set 10 minutes of caching for responses with codes 200 and 302 and 1 minute for responses with code 404.

If only caching time is specified,

```nginx
proxy_cache_valid 5m;
```

then only 200, 301, and 302 responses are cached.

In addition, the `any` parameter can be specified to cache any responses:

```nginx
proxy_cache_valid 200 302 10m;
proxy_cache_valid 301      1h;
proxy_cache_valid any      1m;
```

#### NOTE
Parameters of caching can also be set directly in the response header. This has higher priority than setting of caching time using the directive.

* The `X-Accel-Expires` header field sets caching time of a response in seconds. The zero value disables caching for a response. If the value starts with the `@` prefix, it sets an absolute time in seconds since Epoch, up to which the response may be cached.
* If the header does not include the `X-Accel-Expires` field, parameters of caching may be set in the header fields `Expires` or `Cache-Control`.
* If the header includes the `Set-Cookie` field, such a response will not be cached.
* If the header includes the `Vary` field with the special value "`*`", such a response will not be cached. If the header includes the `Vary` field with another value, such a response will be cached taking into account the corresponding request header fields.

Processing of one or more of these response header fields can be disabled using the [proxy_ignore_headers](#proxy-ignore-headers) directive.





### proxy_connect_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_connect_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `proxy_connect_timeout 60s;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                 |

Defines a timeout for establishing a connection with a proxied server. It should be noted that this timeout cannot usually exceed 75 seconds.

#### NOTE
This timeout does not govern idle connections: how long an already-open one
is kept for reuse is set by [keepalive_timeout](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive-timeout) in an upstream block
whose connections are cached with [keepalive](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive).





### proxy_connection_drop

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_connection_drop` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units) | `on` | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `proxy_connection_drop off;`                                                                                                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                                |

Enables termination of all active connections to the proxied server after it has been
removed from the group or marked as permanently unavailable by a [reresolve](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve) process or the [API command](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-config-methods)
`DELETE`.
Idle connections in the [cache](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive) are not affected.

A connection is terminated when the next read or write event is processed for
either the client or the proxied server.

Setting time enables a connection termination [timeout](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);
with `on` set, connections are dropped immediately.





### proxy_cookie_domain

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_cookie_domain` `off`;

`proxy_cookie_domain` domain replacement;   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------|
| Default                                                                                  | `proxy_cookie_domain off;`                                                        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                            |

Sets a text that should be changed in the domain attribute of the `Set-Cookie` header fields of a proxied server response. Suppose a proxied server returned the `Set-Cookie` header field with the attribute "domain=localhost". The directive

```nginx
proxy_cookie_domain localhost example.org;
```

will rewrite this attribute to "domain=example.org".

The leading dot in the domain and replacement strings, as well as in the domain attribute, is ignored. The value is case-insensitive.

The domain and replacement strings can contain variables:

```nginx
proxy_cookie_domain www.$host $host;
```

The directive can also be specified using regular expressions. In this case, domain should start with the "~" symbol. The regular expression can contain named and positional captures, and replacement can reference them:

```nginx
proxy_cookie_domain ~\.(?P[-0-9a-z]+\.[a-z]+)$ $sl_domain;
```

Multiple proxy_cookie_domain directives may be specified at the same level:

```nginx
proxy_cookie_domain localhost example.org;
proxy_cookie_domain ~\.([a-z]+\.[a-z]+)$ $1;
```

If several directives can be applied to the cookie, the first one will be chosen.

The `off` parameter cancels the effect of the proxy_cookie_domain directives inherited from the previous configuration level.





### proxy_cookie_flags

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_cookie_flags` `off` | cookie [flag ...];   |
|------------------------------------------------------------------------------------------|---------------------------------------------------|
| Default                                                                                  | `proxy_cookie_flags off;`                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                            |

Sets one or more flags for the cookie. The cookie can contain variables. The flag can contain variables.

The `secure`, `httponly`, `samesite=strict`,
`samesite=lax`, `samesite=none` parameters add the corresponding
flags.

The `nosecure`, `nohttponly`, `nosamesite` parameters remove
the corresponding flags.

The cookie can also be specified using regular expressions. In this case, cookie should start with a "~" symbol.

Several `proxy_cookie_flags` directives can be specified on the same
configuration level:

```nginx
proxy_cookie_flags one httponly;
proxy_cookie_flags ~ nosecure samesite=strict;
```

If several directives can be applied to the cookie, the first matching directive will be chosen. In the example, the `httponly` flag is added to the cookie `one`, for all other cookies the `samesite=strict` flag is added and the `secure` flag is deleted.

The `off` parameter cancels the effect of the proxy_cookie_flags directives inherited from the previous configuration level.





### proxy_cookie_path

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_cookie_path` `off`;

`proxy_cookie_path` path replacement;   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| Default                                                                                  | `proxy_cookie_path off;`                                                    |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                      |

Sets a text that should be changed in the path attribute of the
`Set-Cookie` header fields of a proxied server response. Suppose a proxied
server returned the `Set-Cookie` header field with the attribute
"path=/two/some/uri/". The directive

```nginx
proxy_cookie_path /two/ /;
```

will rewrite this attribute to "path=/some/uri/".

The path and replacement strings can contain variables:

```nginx
proxy_cookie_path $uri /some$uri;
```

The directive can also be specified using regular expressions. In this case,
path should either start with a "~" symbol for a case-sensitive matching, or
with the "~\*" symbols for case-insensitive matching. The regular expression can
contain named and positional captures, and replacement can reference them:

```nginx
proxy_cookie_path ~*^/user/([^/]+) /u/$1;
```

Several proxy_cookie_path directives can be specified on the same level:

```nginx
proxy_cookie_path /one/ /;
proxy_cookie_path / /two/;
```

If several directives can be applied to the cookie, the first matching directive will be chosen.

The `off` parameter cancels the effect of the proxy_cookie_path directives inherited from the previous configuration level.





### proxy_force_ranges

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_force_ranges` `on` | `off`;   |
|------------------------------------------------------------------------------------------|--------------------------------------|
| Default                                                                                  | `proxy_force_ranges off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location               |

Enables byte-range support for both cached and uncached responses from the proxied server regardless of the `Accept-Ranges` field in these responses.





### proxy_headers_hash_bucket_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_headers_hash_bucket_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `proxy_headers_hash_bucket_size 64;`                                                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                          |

Sets the bucket size for hash tables used by the [proxy_hide_header](#proxy-hide-header) and [proxy_set_header](#proxy-set-header) directives. The details of setting up hash tables are provided [separately](https://en.angie.software//angie/docs/configuration/configfile.md#configure-hashes).





### proxy_headers_hash_max_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_headers_hash_max_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `proxy_headers_hash_max_size 512;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                       |

Sets the maximum size of hash tables used by the [proxy_hide_header](#proxy-hide-header) and [proxy_set_header](#proxy-set-header) directives. The details of setting up hash tables are provided [separately](https://en.angie.software//angie/docs/configuration/configfile.md#configure-hashes).





### proxy_hide_header

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_hide_header` field;   |
|------------------------------------------------------------------------------------------|------------------------------|
| Default                                                                                  | —                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location       |

By default, Angie does not pass the header fields `Date`, `Server`, `X-Pad`, and `X-Accel-...` from the response of a proxied server to a client. The proxy_hide_header directive sets additional fields that will not be passed. If, on the contrary, the passing of fields needs to be permitted, the [proxy_pass_header](#proxy-pass-header) directive can be used.





### proxy_http3_hq

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_http3_hq` `on` | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | `proxy_http3_hq off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                     |

Toggles the special `hq-interop` negotiation mode,
which is used for
[QUIC](#proxy-http-version)
[interop tests](https://github.com/marten-seemann/quic-interop-runner)
that Angie relies on.

#### WARNING
Enable this mode only to run specialized tests that explicitly require it.





### proxy_http3_max_concurrent_streams

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_http3_max_concurrent_streams` number;   |
|------------------------------------------------------------------------------------------|------------------------------------------------|
| Default                                                                                  | `proxy_http3_max_concurrent_streams 128;`      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                                   |

Initializes HTTP/3 and QUIC settings
and sets the maximum number of concurrent HTTP/3 request streams in a
[connection](#proxy-http-version).
Requires enabling [keepalive connections](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive).





### proxy_http3_max_table_capacity

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_http3_max_table_capacity` number;   |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| Default                                                                                  | `proxy_http3_max_table_capacity 4096;`     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                     |

Sets the [dynamic table](https://www.ietf.org/archive/id/draft-ietf-quic-qpack-20.html#name-dynamic-table)
capacity for proxy connections.

#### NOTE
A similar directive [http3_max_table_capacity](https://en.angie.software//angie/docs/configuration/modules/http/http_v3.md#http3-max-table-capacity)
sets this value for server connections.
To avoid errors, dynamic table usage
is disabled when caching is enabled in proxy mode.





### proxy_http3_stream_buffer_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_http3_stream_buffer_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `proxy_http3_stream_buffer_size 64k;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                                                                                                                    |

Sets the [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units) of the buffer used for reading and writing
[QUIC streams](#proxy-http-version).





### proxy_http_version

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_http_version` `1.0` | `1.1` | `2` | `3`;      |
|------------------------------------------------------------------------------------------|------------------------------------------------------|
| Default                                                                                  | `proxy_http_version 1.1;`                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location, if in location, limit_except |

Sets the HTTP protocol version for proxying.
Version 1.1 or higher
is recommended for use with
[keepalive connections](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive).





### proxy_ignore_client_abort

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_ignore_client_abort` `on` | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| Default                                                                                  | `proxy_ignore_client_abort off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                      |

Determines whether the connection with a proxied server should be closed when a client closes the connection without waiting for a response.





### proxy_ignore_headers

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_ignore_headers` field ...;   |
|------------------------------------------------------------------------------------------|-------------------------------------|
| Default                                                                                  | —                                   |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location              |

Disables processing of certain response header fields from the proxied server. The following fields can be ignored: `X-Accel-Redirect`, `X-Accel-Expires`, `X-Accel-Limit-Rate`, `X-Accel-Buffering`, `X-Accel-Charset`, `Expires`, `Cache-Control`, `Set-Cookie`, and `Vary`.

If not disabled, processing of these header fields has the following effect:

* `X-Accel-Expires`, `Expires`, `Cache-Control`, `Set-Cookie`, and `Vary` set the parameters of response [caching](#proxy-cache-valid);
* `X-Accel-Redirect` performs an [internal redirect](https://en.angie.software//angie/docs/configuration/modules/http/index.md#internal) to the specified URI;
* `X-Accel-Limit-Rate` sets the [rate limit](https://en.angie.software//angie/docs/configuration/modules/http/index.md#limit-rate) for transmission of a response to a client;
* `X-Accel-Buffering` enables or disables [buffering](#proxy-buffering) of a response;
* `X-Accel-Charset` sets the desired [charset](https://en.angie.software//angie/docs/configuration/modules/http/http_charset.md#id1) of a response.





### proxy_intercept_errors

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_intercept_errors` `on` | `off`;   |
|------------------------------------------------------------------------------------------|------------------------------------------|
| Default                                                                                  | `proxy_intercept_errors off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                   |

Determines whether proxied responses with codes greater than or equal to 300 should be passed to a client or be intercepted and redirected to Angie for processing with the [error_page](https://en.angie.software//angie/docs/configuration/modules/http/index.md#error-page) directive.





### proxy_limit_rate

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_limit_rate` rate;   |
|------------------------------------------------------------------------------------------|----------------------------|
| Default                                                                                  | `proxy_limit_rate 0;`      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location     |

Limits the speed of reading the response from the proxied server.
The rate is specified in bytes per second and can contain variables.

| `0`   | disables rate limiting   |
|-------|--------------------------|

#### NOTE
The limit is set per a request, so if Angie simultaneously opens two connections to the proxied server, the overall rate will be twice as much as the specified limit. The limitation works only if [buffering](#proxy-buffering) of responses from the proxied server is enabled.





### proxy_max_temp_file_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_max_temp_file_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `proxy_max_temp_file_size 1024m;`                                                                                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                    |

When [buffering](#proxy-buffering) of responses from the proxied server is enabled, and the whole response does not fit into the buffers set by the [proxy_buffer_size](#proxy-buffer-size) and [proxy_buffers](#proxy-buffers) directives, a part of the response can be saved to a temporary file. This directive sets the maximum size of the temporary file. The size of data written to the temporary file at a time is set by the [proxy_temp_file_write_size](#proxy-temp-file-write-size) directive.

| `0`   | disables buffering of responses to temporary files   |
|-------|------------------------------------------------------|

#### NOTE
This restriction does not apply to responses that will be [cached](#proxy-cache) or [stored](#proxy-store) on disk.





### proxy_method

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_method` method;   |
|------------------------------------------------------------------------------------------|--------------------------|
| Default                                                                                  | —                        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location   |

Specifies the HTTP method to use in requests forwarded to the proxied server instead of the method from the client request. Parameter value can contain variables.





### proxy_next_upstream

#### Versionchanged
Changed in version 1.11.0: If all servers in the upstream group are unavailable or respond with a
status considered an error by this directive (and its counterparts for
other protocols), Angie now always returns its own error page instead
of the response from the last server.

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_next_upstream` `error` | `timeout` | `invalid_header` | `http_500` | `http_502` | `http_503` | `http_504` | `http_403` | `http_404` | `http_429` | `non_idempotent` | `off` ...;   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `proxy_next_upstream error timeout;`                                                                                                                                                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                                                                                    |

Specifies in which cases a request should be passed to the next server in the [upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream) group:

| `error`          | an error occurred while establishing a connection with the server, passing a request to it, or reading the response header;                                                                                                                                                                             |
|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `timeout`        | a timeout has occurred while establishing a connection with the server, passing a request to it, or reading the response header;                                                                                                                                                                        |
| `invalid_header` | a server returned an empty or invalid response;                                                                                                                                                                                                                                                         |
| `http_500`       | a server returned a response with the code 500;                                                                                                                                                                                                                                                         |
| `http_502`       | a server returned a response with the code 502;                                                                                                                                                                                                                                                         |
| `http_503`       | a server returned a response with the code 503;                                                                                                                                                                                                                                                         |
| `http_504`       | a server returned a response with the code 504;                                                                                                                                                                                                                                                         |
| `http_403`       | a server returned a response with the code 403;                                                                                                                                                                                                                                                         |
| `http_404`       | a server returned a response with the code 404;                                                                                                                                                                                                                                                         |
| `http_429`       | a server returned a response with the code 429;                                                                                                                                                                                                                                                         |
| `non_idempotent` | normally, requests with a [non-idempotent](https://datatracker.ietf.org/doc/html/rfc7231#section-4.2.2) method
(`POST`, `LOCK`, `PATCH`) are not passed to the next
server if a request has been sent to an upstream server; enabling this
option explicitly allows retrying such requests; |
| `off`            | disables passing a request to the next server.                                                                                                                                                                                                                                                          |

If all upstream servers are unavailable or return a response with a status
considered an error by `proxy_next_upstream`, Angie returns its own
standard error page instead of the response body from the last upstream server.

#### NOTE
It should be understood that passing a request to the next server is only possible if nothing has been sent to a client yet. That is, if an error or timeout occurs in the middle of the transferring of a response, fixing this is impossible.

The directive also defines what is considered an [unsuccessful attempt](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) of communication with a server.

| `error`

`timeout`

`invalid_header`                                       | are always considered unsuccessful attempts, even if they are not specified in the directive   |
|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
| `http_500`

`http_502`

`http_503`

`http_504`

`http_429` | are considered unsuccessful attempts only if they are specified in the directive               |
| `http_403`

`http_404`                                                             | are never considered unsuccessful attempts                                                     |

Passing a request to the next server can be limited by the [number of tries](#proxy-next-upstream-tries) and by [time](#proxy-next-upstream-timeout).





### proxy_next_upstream_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_next_upstream_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `proxy_next_upstream_timeout 0;`                                                                                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                       |

Limits the time during which a request can be passed to the [next server](#proxy-next-upstream).

| `0`   | disables this limitation   |
|-------|----------------------------|





### proxy_next_upstream_tries

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_next_upstream_tries` number;   |
|------------------------------------------------------------------------------------------|---------------------------------------|
| Default                                                                                  | `proxy_next_upstream_tries 0;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                |

Limits the number of possible tries for passing a request to the [next server](#proxy-next-upstream).

| `0`   | disables this limitation   |
|-------|----------------------------|





### proxy_no_cache

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_no_cache` string ...;   |
|------------------------------------------------------------------------------------------|--------------------------------|
| Default                                                                                  | —                              |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location         |

Defines conditions under which the response will not be saved to a cache. If at least one value of the string parameters is not empty and is not equal to "0" then the response will not be saved:

```nginx
proxy_no_cache $cookie_nocache $arg_nocache$arg_comment;
proxy_no_cache $http_pragma    $http_authorization;
```

Parameter values can contain variables.

Can be used along with the [proxy_cache_bypass](#proxy-cache-bypass) directive.





### proxy_pass

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_pass` uri;                      |
|------------------------------------------------------------------------------------------|----------------------------------------|
| Default                                                                                  | —                                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | location, if in location, limit_except |

Sets the protocol and address of a proxied server and an optional URI to which a location should be mapped. As a protocol, `http` or `https` can be specified. The address can be specified as a domain name or IP address, and an optional port:

```nginx
proxy_pass http://localhost:8000/uri/;
```

or as a UNIX-domain socket path specified after the word `unix` and enclosed in colons:

```nginx
proxy_pass http://unix:/tmp/backend.socket:/uri/;
```

If a domain name resolves to several addresses, all of them will be used in a round-robin fashion. In addition, an address can be specified as a [server group](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream).

Parameter value can contain variables. In this case, if an address is specified as a domain name, the name is searched among the described server groups, and, if not found, is determined using a [resolver](https://en.angie.software//angie/docs/configuration/modules/http/index.md#resolver).

#### NOTE
A domain name in `proxy_pass` that contains no variables and does not
match a defined [server group](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream) implicitly creates a
server group of a single server, equivalent to:

```nginx
upstream example.com {
    server example.com;
}
```

These server group names are shared across the entire `http`
configuration, regardless of the `server` block where
`proxy_pass` appears. Because the implicitly created `server`
has no [resolve](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve) parameter, the name is resolved once, at
configuration load time, and the obtained addresses are used until the next
reload, even when a [resolver](https://en.angie.software//angie/docs/configuration/modules/http/index.md#resolver) is configured.

As a result, a `proxy_pass` whose variable evaluates to that same name
reuses this existing server group with its load-time addresses instead of
resolving the name per request through the [resolver](https://en.angie.software//angie/docs/configuration/modules/http/index.md#resolver). To
re-resolve the name at runtime and follow DNS changes, define the server
group explicitly and add the [resolve](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve) parameter to its
`server`.



A request URI is passed to the server as follows:

* If the `proxy_pass` directive is specified **with a URI**, then when a request is passed to the server, the part of a [normalized](https://en.angie.software//angie/docs/configuration/modules/http/index.md#location) request URI matching the location is replaced by a URI specified in the directive:

```nginx
location /name/ {
    proxy_pass http://127.0.0.1/remote/;
}
```

* If `proxy_pass` is specified **without a URI**, the request URI is passed to the server in the same form as sent by a client when the original request is processed, or the full normalized request URI is passed when processing the changed URI:

```nginx
location /some/path/ {
    proxy_pass http://127.0.0.1;
}
```

In some cases, the part of a request URI to be replaced cannot be determined:

* When `location` is specified using a regular expression, and also inside named `location`.

In these cases, `proxy_pass` should be specified without a URI.

* When the URI is changed inside a proxied `location` using the [rewrite](https://en.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#id5) directive, and this same configuration will be used to process a request (break):

```nginx
location /name/ {
    rewrite    /name/([^/]+) /users?name=$1 break;
    proxy_pass http://127.0.0.1;
}
```

In this case, the URI specified in the directive is ignored and the full changed request URI is passed to the server.

* When variables are used in `proxy_pass`:

```nginx
location /name/ {
    proxy_pass http://127.0.0.1$request_uri;
}
```

In this case, if URI is specified in the directive, it is passed to the server as is, replacing the original request URI.

[WebSocket](https://en.angie.software//angie/docs/configuration/processing.md#websocket-proxy) proxying requires special configuration.

#### NOTE
If `proxy_pass` is placed in a `location` with a trailing slash in the prefix
(for example, `location /name/`),
and the [auto_redirect](https://en.angie.software//angie/docs/configuration/modules/http/index.md#auto-redirect) directive is set to `default`,
requests without a trailing slash will be redirected (`/name -> /name/`).





### proxy_pass_header

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_pass_header` field ...;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | —                                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location           |

Permits passing [otherwise disabled](#proxy-hide-header) header fields from a proxied server to a client.





### proxy_pass_request_body

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_pass_request_body` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-------------------------------------------|
| Default                                                                                  | `proxy_pass_request_body on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                    |

Indicates whether the original request body is passed to the proxied server.

```nginx
location /x-accel-redirect-here/ {
    proxy_method GET;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";

    proxy_pass ...;
}
```

See also the [proxy_set_header](#proxy-set-header) and [proxy_pass_request_headers](#proxy-pass-request-headers) directives.





### proxy_pass_request_headers

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_pass_request_headers` `on` | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------------------------|
| Default                                                                                  | `proxy_pass_request_headers on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                       |

Indicates whether the header fields of the original request are passed to the proxied server.

```nginx
location /x-accel-redirect-here/ {
    proxy_method GET;
    proxy_pass_request_headers off;
    proxy_pass_request_body off;

    proxy_pass ...;
}
```

See also the [proxy_set_header](#proxy-set-header) and [proxy_pass_request_body](#proxy-pass-request-body) directives.





### proxy_pass_trailers

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_pass_trailers` `on` | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------------|
| Default                                                                                  | `proxy_pass_trailers off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                |

Allows passing trailer fields from a proxied server to a client.

A trailer section in HTTP/1.1 is [explicitly enabled](https://datatracker.ietf.org/doc/html/rfc9110#section-6.5.1).

```nginx
location / {
    proxy_http_version 1.1;
    proxy_set_header Connection "te";
    proxy_set_header TE "trailers";
    proxy_pass_trailers on;

    proxy_pass ...;
}
```





### proxy_quic_active_connection_id_limit

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_quic_active_connection_id_limit` number;   |
|------------------------------------------------------------------------------------------|---------------------------------------------------|
| Default                                                                                  | `proxy_quic_active_connection_id_limit 2;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                                      |

Sets the [QUIC](#proxy-http-version)
`active_connection_id_limit` transport parameter value.
This is the maximum number of active
[connection IDs](https://www.rfc-editor.org/rfc/rfc9000.html#name-connection-id)
that can be maintained per server.





### proxy_quic_gso

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_quic_gso` `on` | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | `proxy_quic_gso off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                     |

Toggles sending data in
[QUIC](#proxy-http-version)-optimized
batch mode using
[generic segmentation offload](https://docs.kernel.org/networking/segmentation-offloads.html#generic-segmentation-offload).





### proxy_quic_host_key

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_quic_host_key` file;   |
|------------------------------------------------------------------------------------------|-------------------------------|
| Default                                                                                  | —                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                  |

Sets a file with the secret key
used with [QUIC](#proxy-http-version)
to encrypt
[Stateless Reset](https://www.rfc-editor.org/rfc/rfc9000.html#name-stateless-reset)
and
[Address Validation](https://www.rfc-editor.org/rfc/rfc9000.html#address-validation)
tokens.
By default, a random key is generated at each restart.
Tokens generated with old keys are not accepted.





### proxy_read_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_read_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `proxy_read_timeout 60s;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                              |

Defines a timeout for reading a response from the proxied server. The timeout is set only between two successive read operations, not for the transmission of the whole response. If the proxied server does not transmit anything within this time, the connection is closed.





### proxy_redirect

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_redirect` `default`;

`proxy_redirect` `off`;

`proxy_redirect` redirect replacement;   |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `proxy_redirect default;`                                                                                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                         |

Sets the text that should be changed in the "Location" and "Refresh" header fields of a proxied server response.

Suppose a proxied server returned the header field:

```console
Location: http://localhost:8000/two/some/uri/
```

The directive

```nginx
proxy_redirect http://localhost:8000/two/ http://frontend/one/;
```

will rewrite this string to:

```console
Location: http://frontend/one/some/uri/
```

A server name may be omitted in the replacement string:

```nginx
proxy_redirect http://localhost:8000/two/ /;
```

then the primary server's name and port, if different from 80, will be inserted.

The default replacement specified by the `default` parameter uses the parameters of the [location](https://en.angie.software//angie/docs/configuration/modules/http/index.md#location) and [proxy_pass](#proxy-pass) directives. Hence, the two configurations below are equivalent:

```nginx
location /one/ {
    proxy_pass     http://upstream:port/two/;
    proxy_redirect default;
}
```

```nginx
location /one/ {
    proxy_pass     http://upstream:port/two/;
    proxy_redirect http://upstream:port/two/ /one/;
}
```

#### WARNING
The `default` parameter is not permitted if [proxy_pass](#proxy-pass) is specified using variables.

A replacement string can contain variables:

```nginx
proxy_redirect http://localhost:8000/ http://$host:$server_port/;
```

A redirect can also contain variables:

```nginx
proxy_redirect http://$proxy_host:8000/ /;
```

The directive can be specified using regular expressions. In this case, redirect should either start with the "~" symbol for a case-sensitive matching, or with the "~\*" symbols for case-insensitive matching. The regular expression can contain named and positional captures, and replacement can reference them:

```nginx
proxy_redirect ~^(http://[^:]+):\d+(/.+)$ $1$2;
proxy_redirect ~*/user/([^/]+)/(.+)$      http://$1.example.com/$2;
```

Several proxy_redirect directives can be specified on the same level:

```nginx
proxy_redirect default;
proxy_redirect http://localhost:8000/  /;
proxy_redirect http://www.example.com/ /;
```

If several directives can be applied to the header fields of a proxied server response, the first matching directive will be chosen.

The `off` parameter cancels the effect of the proxy_redirect directives inherited from the previous configuration level.

Using this directive, it is also possible to add host names to relative redirects issued by a proxied server:

```nginx
proxy_redirect / /;
```





### proxy_request_buffering

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_request_buffering` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-------------------------------------------|
| Default                                                                                  | `proxy_request_buffering on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                    |

Enables or disables buffering of a client request body.

| `on`   | the entire request body is [read](https://en.angie.software//angie/docs/configuration/modules/http/index.md#client-body-buffer-size) from the client before sending the request to a proxied server.                   |
|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off`  | the request body is sent to the proxied server immediately as it is received. In this case, the request cannot be passed to the [next server](#proxy-next-upstream) if Angie already started sending the request body. |

When HTTP/1.1 chunked transfer encoding is used to send the original request
body, the request body is buffered regardless of the directive value unless
HTTP/1.1, HTTP/2, or HTTP/3 is [enabled](#proxy-http-version) for
proxying.





### proxy_send_lowat

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_send_lowat` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `proxy_send_lowat 0;`                                                                                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                            |

If the directive is set to a non-zero value, Angie will try to minimize the number of send operations on outgoing connections to a proxied server by using either NOTE_LOWAT flag of the [kqueue](https://en.angie.software//angie/docs/configuration/processing.md#kqueue) method, or the SO_SNDLOWAT socket option, with the specified size.

#### NOTE
This directive is ignored on Linux, Solaris, and Windows.





### proxy_send_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_send_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `proxy_send_timeout 60s;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                              |

Sets a timeout for transmitting a request to the proxied server. The timeout is set only between two successive write operations, not for the transmission of the whole request. If the proxied server does not receive anything within this time, the connection is closed.





### proxy_set_body

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_set_body` value;   |
|------------------------------------------------------------------------------------------|---------------------------|
| Default                                                                                  | —                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location    |

Allows redefining the request body passed to the proxied server. The value can contain variables.





### proxy_set_header

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_set_header` field value;      |
|------------------------------------------------------------------------------------------|--------------------------------------|
| Default                                                                                  | `proxy_set_header Host $proxy_host;` |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location               |

Allows redefining or appending fields to the request header [passed](#proxy-pass-request-headers) to the proxied server. The value can contain variables. These directives are inherited from the previous configuration level if and only if there are no proxy_set_header directives defined on the current level. By default, only two fields are redefined:

```nginx
proxy_set_header Host       $proxy_host;
proxy_set_header Connection close;
```

If caching is enabled, the header fields `If-Modified-Since`, `If-Unmodified-Since`, `If-None-Match`, `If-Match`, `Range`, and `If-Range` from the original request are not passed to the proxied server.

An unchanged "Host" request header field can be passed like this:

```nginx
proxy_set_header Host       $http_host;
```

However, if this field is not present in a client request header then nothing will be passed. In such a case it is better to use the [$host](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-host) variable - its value equals the server name in the "Host" request header field or the primary server name if this field is not present:

```nginx
proxy_set_header Host       $host;
```

In addition, the server name can be passed together with the port of the proxied server:

```nginx
proxy_set_header Host       $host:$proxy_port;
```

If the value of a header field is an empty string then this field will not be passed to a proxied server:

```nginx
proxy_set_header Accept-Encoding "";
```





### proxy_socket_keepalive

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_socket_keepalive` `on` | `off`;   |
|------------------------------------------------------------------------------------------|------------------------------------------|
| Default                                                                                  | `proxy_socket_keepalive off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                   |

Configures the "TCP keepalive" behavior for outgoing connections to a proxied server.

| `off`   | By default, the operating system's settings are in effect for the socket.   |
|---------|-----------------------------------------------------------------------------|
| `on`    | The SO_KEEPALIVE socket option is turned on for the socket.                 |





### proxy_ssl_certificate

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_ssl_certificate` file [file];   |
|------------------------------------------------------------------------------------------|----------------------------------------|
| Default                                                                                  | —                                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                 |

Specifies a file with the certificate in the PEM format used for authentication to a proxied HTTPS server. The file name can contain variables.

When [proxy_ssl_ntls](#proxy-ssl-ntls) is enabled, the directive accepts two arguments instead of one:

```nginx
location /proxy {
    proxy_ssl_ntls  on;

    proxy_ssl_certificate      sign.crt enc.crt;
    proxy_ssl_certificate_key  sign.key enc.key;

    proxy_ssl_ciphers "ECC-SM2-WITH-SM4-SM3:ECDHE-SM2-WITH-SM4-SM3:RSA";

    proxy_pass https://backend:443;
}
```





### proxy_ssl_certificate_cache

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_ssl_certificate_cache` `off`;

`proxy_ssl_certificate_cache` `max=`N [`inactive=`time] [`valid=`time];   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `proxy_ssl_certificate_cache off;`                                                                                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                  |

Defines a cache that stores [SSL certificates](#proxy-ssl-certificate) and [secret keys](#proxy-ssl-certificate-key) specified using variables.

The directive supports the following parameters:

- `max` — sets the maximum number of elements in the cache. When the cache overflows, the least recently used (LRU) elements are removed.
- `inactive` — defines the time after which an element is removed if it has not been accessed during this time, even if still within its `valid` period; each access resets this timer. The default is 10 seconds.
- `valid` — defines the time during which a cached element is considered valid and can be reused. The default is 60 seconds. After this period, certificates are reloaded or revalidated.
- `off` — disables the cache.

Example:

```nginx
proxy_ssl_certificate       $proxy_ssl_server_name.crt;
proxy_ssl_certificate_key   $proxy_ssl_server_name.key;
proxy_ssl_certificate_cache max=1000 inactive=20s valid=1m;
```





### proxy_ssl_certificate_key

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_ssl_certificate_key` file [file];   |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| Default                                                                                  | —                                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                     |

Specifies a file with the secret key in the PEM format used for authentication to a proxied HTTPS server.

The value `engine:`name`:id` can be specified instead of the file, which loads a secret key with a specified id from the OpenSSL engine name.

The value `store:scheme:id` can be specified instead of the file, which is used to load a secret key with a specified id and OpenSSL provider registered URI scheme, such as [pkcs11](https://datatracker.ietf.org/doc/html/rfc7512).

The file name can contain variables.

When [proxy_ssl_ntls](#proxy-ssl-ntls) is enabled, the directive accepts two arguments instead of one:

```nginx
location /proxy {
    proxy_ssl_ntls  on;

    proxy_ssl_certificate      sign.crt enc.crt;
    proxy_ssl_certificate_key  sign.key enc.key;

    proxy_ssl_ciphers "ECC-SM2-WITH-SM4-SM3:ECDHE-SM2-WITH-SM4-SM3:RSA";

    proxy_pass https://backend:443;
}
```





### proxy_ssl_ciphers

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_ssl_ciphers` ciphers;   |
|------------------------------------------------------------------------------------------|--------------------------------|
| Default                                                                                  | `proxy_ssl_ciphers DEFAULT;`   |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location         |

Specifies the enabled ciphers for requests to a proxied HTTPS server. The ciphers are specified in the format understood by the OpenSSL library.

The list of ciphers depends on the version of OpenSSL installed.
The full list can be viewed using the `openssl ciphers` command.

#### WARNING
The `proxy_ssl_ciphers` directive does *not* configure ciphers for TLS
1.3 when using OpenSSL. To tune TLS 1.3 ciphers with OpenSSL, use the
[proxy_ssl_conf_command](#proxy-ssl-conf-command) directive, which was added to support advanced
SSL configuration.

- In LibreSSL, TLS 1.3 ciphers *can* be configured using
  `proxy_ssl_ciphers`.
- In BoringSSL, TLS 1.3 ciphers cannot be configured at all.





### proxy_ssl_conf_command

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_ssl_conf_command` name value;   |
|------------------------------------------------------------------------------------------|----------------------------------------|
| Default                                                                                  | —                                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                 |

Sets arbitrary OpenSSL configuration [commands](https://docs.openssl.org/master/man3/SSL_CONF_cmd/) when establishing a connection with the proxied HTTPS server.

#### NOTE
The directive is supported when using OpenSSL 1.0.2 or higher.
To configure TLS 1.3 ciphers with OpenSSL, use the `ciphersuites` command.

Several proxy_ssl_conf_command directives can be specified on the same level. These directives are inherited from the previous configuration level if and only if there are no proxy_ssl_conf_command directives defined on the current level.

#### WARNING
Note that configuring OpenSSL directly might result in unexpected behavior.





### proxy_ssl_crl

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_ssl_crl` file;   |
|------------------------------------------------------------------------------------------|-------------------------|
| Default                                                                                  | —                       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location  |

Specifies a file with revoked certificates (CRL) in the PEM format used to [verify](#proxy-ssl-verify) the certificate of the proxied HTTPS server.





### proxy_ssl_keylog_file

#### Versionadded
Added in version 1.12.0.

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_ssl_keylog_file` file;   |
|------------------------------------------------------------------------------------------|---------------------------------|
| Default                                                                                  | —                               |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location          |

Specifies a file to log SSL/TLS keys for connections to proxied HTTPS servers in the context,
using the [SSLKEYLOGFILE](https://www.ietf.org/archive/id/draft-thomson-tls-keylogfile-00.html)
format used by tools such as Wireshark to decrypt captured TLS traffic.

The directive should not be used with LibreSSL.

#### WARNING
The file contains sensitive TLS key material that can decrypt captured
traffic for the corresponding connections. Use this directive only for
debugging or protocol analysis, restrict access to the file, and remove it
when no longer needed.





### proxy_ssl_name

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_ssl_name` name;        |
|------------------------------------------------------------------------------------------|-------------------------------|
| Default                                                                                  | `proxy_ssl_name $proxy_host;` |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location        |

Allows overriding the server name used to [verify](#proxy-ssl-verify) the certificate of the proxied HTTPS server and to be [passed through SNI](#proxy-ssl-server-name) when establishing a connection with the proxied HTTPS server.

The server name can also be specified with variables.

By default, the host part of the [proxy_pass](#proxy-pass) URL is used.





### proxy_ssl_ntls

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_ssl_ntls` `on` | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | `proxy_ssl_ntls off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                     |

Enables client-side support for NTLS using the [TongSuo](https://github.com/Tongsuo-Project/Tongsuo) TLS library.

```nginx
location /proxy {
    proxy_ssl_ntls  on;

    proxy_ssl_certificate      sign.crt enc.crt;
    proxy_ssl_certificate_key  sign.key enc.key;

    proxy_ssl_ciphers "ECC-SM2-WITH-SM4-SM3:ECDHE-SM2-WITH-SM4-SM3:RSA";

    proxy_pass https://backend:443;
}
```

#### NOTE
Angie must be built with the `--with-ntls` configuration parameter and the corresponding SSL library with NTLS support

```default
./configure --with-openssl=../Tongsuo-8.3.0 \
            --with-openssl-opt=enable-ntls  \
            --with-ntls
```





### proxy_ssl_password_file

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_ssl_password_file` file;   |
|------------------------------------------------------------------------------------------|-----------------------------------|
| Default                                                                                  | —                                 |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location            |

Specifies a file with passphrases for [secret keys](#proxy-ssl-certificate-key) where each passphrase is specified on a separate line. Passphrases are tried in turn when loading the key.





### proxy_ssl_protocols

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_ssl_protocols` [`SSLv2`] [`SSLv3`] [`TLSv1`] [`TLSv1.1`] [`TLSv1.2`] [`TLSv1.3`];   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|
| Default                                                                                  | `proxy_ssl_protocols TLSv1.2 TLSv1.3;`                                                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                     |

Enables the specified protocols for requests to a proxied HTTPS server.





### proxy_ssl_server_name

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_ssl_server_name` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| Default                                                                                  | `proxy_ssl_server_name off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                  |

Enables or disables passing the server name
set by the [proxy_ssl_name](#proxy-ssl-name) directive
via the
[Server Name Indication](http://en.wikipedia.org/wiki/Server_Name_Indication)
TLS extension
(SNI,
[RFC 6066](https://datatracker.ietf.org/doc/html/rfc6066.html))
when establishing a connection with the proxied HTTPS server.





### proxy_ssl_session_reuse

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_ssl_session_reuse` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-------------------------------------------|
| Default                                                                                  | `proxy_ssl_session_reuse on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                    |

Determines whether SSL sessions can be reused when working with the proxied server. If the errors "SSL3_GET_FINISHED:digest check failed" appear in the logs, try disabling session reuse.





### proxy_ssl_trusted_certificate

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_ssl_trusted_certificate` file;   |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| Default                                                                                  | —                                       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                  |

Specifies a file with trusted CA certificates in the PEM format used to [verify](#proxy-ssl-verify) the certificate of the proxied HTTPS server.





### proxy_ssl_verify

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_ssl_verify` `on` | `off`;   |
|------------------------------------------------------------------------------------------|------------------------------------|
| Default                                                                                  | `proxy_ssl_verify off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location             |

Enables or disables verification of the proxied HTTPS server certificate.





### proxy_ssl_verify_depth

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_ssl_verify_depth` number;   |
|------------------------------------------------------------------------------------------|------------------------------------|
| Default                                                                                  | `proxy_ssl_verify_depth 1;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location             |

Sets the verification depth in the proxied HTTPS server certificate chain.





### proxy_store

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_store` `on` | `off` | string;   |
|------------------------------------------------------------------------------------------|----------------------------------------|
| Default                                                                                  | `proxy_store off;`                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                 |

Enables saving of files to a disk.

| `on`   | saves files according to the paths specified in the [alias](https://en.angie.software//angie/docs/configuration/modules/http/index.md#alias) or [root](https://en.angie.software//angie/docs/configuration/modules/http/index.md#root) directives   |
|--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off`  | disables saving of files                                                                                                                                                                                                                            |

The file name can be set explicitly using a `string` with variables:

```nginx
proxy_store /data/www$original_uri;
```

The modification time of files is set according to the received `Last-Modified` header field in the response. The response is first written to a temporary file, and then the file is renamed. The temporary file and the persistent store for the response can be on different file systems. However, be aware that in this case instead of the cheap rename operation within one file system, the file is copied from one file system to another. It is thus recommended that for any given location both saved files and a directory holding temporary files, set by the [proxy_temp_path](#proxy-temp-path) directive, are put on the same file system.

This directive can be used to create local copies of static unchangeable files, e.g.:

```nginx
location /images/ {
    root               /data/www;
    error_page         404 = /fetch$uri;
}

location /fetch/ {
    internal;

    proxy_pass         http://backend/;
    proxy_store        on;
    proxy_store_access user:rw group:rw all:r;
    proxy_temp_path    /data/temp;

    alias              /data/www/;
}
```

or like this:

```nginx
location /images/ {
    root               /data/www;
    error_page         404 = @fetch;
}

location @fetch {
    internal;

    proxy_pass         http://backend;
    proxy_store        on;
    proxy_store_access user:rw group:rw all:r;
    proxy_temp_path    /data/temp;

    root               /data/www;
}
```





### proxy_store_access

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_store_access` users:permissions ...;   |
|------------------------------------------------------------------------------------------|-----------------------------------------------|
| Default                                                                                  | `proxy_store_access user:rw;`                 |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                        |

Sets access permissions for newly created files and directories, e.g.:

```nginx
proxy_store_access user:rw group:rw all:r;
```

If any `group` or `all` access permissions are specified, then `user` permissions may be omitted:

```nginx
proxy_store_access group:rw all:r;
```





### proxy_temp_file_write_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_temp_file_write_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `proxy_temp_file_write_size 8k|16k;`                                                                                        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                      |

Limits the size of data written to a temporary file at a time, when buffering of responses from the proxied server to temporary files is enabled. By default, size is limited by two buffers set by the [proxy_buffer_size](#proxy-buffer-size) and [proxy_buffers](#proxy-buffers) directives. The maximum size of a temporary file is set by the [proxy_max_temp_file_size](#proxy-max-temp-file-size) directive.





### proxy_temp_path

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_temp_path` path [level1 [level2 [level3]]]\`;                                                                                                                         |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `proxy_temp_path proxy_temp;`
(the path depends on the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#paths) `--http-proxy-temp-path`) |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                                                                       |

Defines a directory for storing temporary files with data received from proxied servers. Up to three-level subdirectory hierarchy can be used underneath the specified directory. For example, in the following configuration

```nginx
proxy_temp_path /spool/angie/proxy_temp 1 2;
```

a temporary file might look like this:

```nginx
/spool/angie/proxy_temp/7/45/00000123457
```

See also the `use_temp_path` parameter of the [proxy_cache_path](#proxy-cache-path) directive.



## Built-in Variables

The http_proxy module supports built-in variables that can be used to compose headers using the [proxy_set_header](#proxy-set-header) directive:



### `$proxy_add_x_forwarded_for`

the `X-Forwarded-For` client request header field with the [$remote_addr](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-remote-addr) variable appended to it, separated by a comma. If the `X-Forwarded-For` field is not present in the client request header, the [$proxy_add_x_forwarded_for](#v-proxy-add-x-forwarded-for) variable is equal to the [$remote_addr](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-remote-addr) variable.



### `$proxy_host`

name and port of a proxied server as specified in the [proxy_pass](#proxy-pass) directive;



### `$proxy_port`

port of a proxied server as specified in the [proxy_pass](#proxy-pass) directive, or the protocol's default port;


# https://en.angie.software/angie/docs/configuration/modules/http/http_random_index.md





# Random Index

The module processes requests ending with the slash character (`/`) and picks a random file in a directory to serve as an index file. The module is processed before the `http_index` module.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module isn't built
by default; it must be enabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--with-http_random_index_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
location / {
    random_index on;
}
```



## Directives





### random_index

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `random_index` `on` | `off`;   |
|------------------------------------------------------------------------------------------|--------------------------------|
| Default                                                                                  | `random_index off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | location                       |

Enables or disables module processing in a surrounding location.


# https://en.angie.software/angie/docs/configuration/modules/http/http_realip.md





# RealIP

The module is used to change the client address and optional port to those sent in the specified header field.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module isn't built
by default; it must be enabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--with-http_realip_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
set_real_ip_from  192.168.1.0/24;
set_real_ip_from  192.168.2.1;
set_real_ip_from  2001:0db8::/32;
real_ip_header    X-Forwarded-For;
real_ip_recursive on;
```



## Directives





### real_ip_header

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `real_ip_header` field | `X-Real-IP` | `X-Forwarded-For` | `proxy_protocol`;   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------|
| Default                                                                                  | `real_ip_header X-Real-IP;`                                                    |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                         |

Defines the request header field whose value will be used to replace the client address.

The request header field value that contains an optional port is also used to replace the client port. The address and port should be specified according to [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986).

The `proxy_protocol` parameter changes the client address to the one from the PROXY protocol header. The PROXY protocol must be previously enabled by setting the proxy_protocol parameter in the [listen](https://en.angie.software//angie/docs/configuration/modules/http/index.md#listen) directive.





### real_ip_recursive

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `real_ip_recursive` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-------------------------------------|
| Default                                                                                  | `real_ip_recursive off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location              |

If recursive search is disabled, the original client address that matches one of the trusted addresses is replaced by the last address sent in the request header field defined by the [real_ip_header](#real-ip-header) directive. If recursive search is enabled, the original client address that matches one of the trusted addresses is replaced by the last non-trusted address sent in the request header field.





### set_real_ip_from

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `set_real_ip_from` address | CIDR | `unix:`;   |
|------------------------------------------------------------------------------------------|------------------------------------------------|
| Default                                                                                  | —                                              |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                         |

Defines trusted addresses that are known to send correct replacement addresses.
If the special value `unix:` is specified, all UNIX domain sockets will be
trusted. Trusted addresses may also be specified using a hostname.



## Built-in Variables



### `$realip_remote_addr`

keeps the original client address



### `$realip_remote_port`

keeps the original client port


# https://en.angie.software/angie/docs/configuration/modules/http/http_referer.md





# Referer

The module is used to block access to a site for requests with invalid values in the `Referer` header field. It should be kept in mind that fabricating a request with an appropriate `Referer` field value is quite easy, and so the intended purpose of this module is not to block such requests thoroughly but to block the mass flow of requests sent by regular browsers. It should also be taken into consideration that regular browsers may not send the `Referer` field even for valid requests.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by
default; it can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-http_referer_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
valid_referers none blocked server_names
               *.example.com example.* www.example.org/galleries/
               ~\.google\.;

if ($invalid_referer) {
    return 403;
}
```



## Directives





### referer_hash_bucket_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `referer_hash_bucket_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `referer_hash_bucket_size 64;`                                                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | server, location                                                                                                          |

Sets the bucket size for the valid referers hash tables. The details of setting up hash tables are provided in a separate [document](https://en.angie.software//angie/docs/configuration/configfile.md#configure-hashes).





### referer_hash_max_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `referer_hash_max_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `referer_hash_max_size 2048;`                                                                                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | server, location                                                                                                       |

Sets the maximum size of the valid referers hash tables. The details of setting up hash tables are provided in a separate [document](https://en.angie.software//angie/docs/configuration/configfile.md#configure-hashes).





### valid_referers

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `valid_referers` `none` | `blocked` | `server_names` | string ...;   |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------|
| Default                                                                                  | —                                                                    |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | server, location                                                     |

Specifies the `Referer` request header field values that will cause the built-in [$invalid_referer](#v-invalid-referer) variable to be set to an empty string. Otherwise, the variable will be set to "1". Search for a match is case-insensitive.

Parameters can be as follows:

| `none`               | the `Referer` field is missing in the request header;                                                                                                                                       |
|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `blocked`            | the `Referer` field is present in the request header, but its value has been deleted by a firewall or proxy server; such values are strings that do not start with `http://` or `https://`; |
| `server_names`       | the `Referer` request header field contains one of the server names;                                                                                                                        |
| `arbitrary string`   | defines a server name and an optional URI prefix. A server name can have an "\*" at the beginning or end. During the checking, the server's port in the `Referer` field is ignored;         |
| `regular expression` | the first symbol should be a "~". It should be noted that an expression will be matched against the text starting after the `http://` or `https://`.                                        |

Example:

```nginx
valid_referers none blocked server_names
               *.example.com example.* www.example.org/galleries/
               ~\.google\.;
```



## Built-in Variables



### `$invalid_referer`

Empty string, if the `Referer` request header field value is considered [valid](#valid-referers), otherwise "1".


# https://en.angie.software/angie/docs/configuration/modules/http/http_rewrite.md






# Rewrite

The module is used to change request URI using PCRE regular expressions, return redirects, and conditionally select configurations.

The [break](#break), [goto](#goto), [if](#if), [return](#return), [rewrite](#id5), and
[set](#set) directives are processed in the following order:

* the directives of this module specified on the server level are executed sequentially;
* repeatedly:
  > * a location is searched based on a request URI;
  > * the directives of this module specified inside the found location are executed sequentially;
  > * the loop is repeated if a request URI was [rewritten](#id5), but [not more](https://en.angie.software//angie/docs/configuration/modules/http/index.md#internal) than 10 times.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by
default; it can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-http_rewrite_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Directives





### break

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `break`;             |
|------------------------------------------------------------------------------------------|----------------------|
| Default                                                                                  | —                    |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | server, location, if |

Stops processing the current set of http_rewrite module directives.

If a directive is specified inside the location, further processing of the request continues in this location.

Example:

```nginx
if ($slow) {
    limit_rate 10k;
    break;
}
```





### goto

#### Versionadded
Added in version 1.12.0.

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `goto` @name;        |
|------------------------------------------------------------------------------------------|----------------------|
| Default                                                                                  | —                    |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | server, location, if |

Stops processing the current set of `http_rewrite` module directives and
performs an unconditional internal redirect to the [named location](https://en.angie.software//angie/docs/configuration/modules/http/index.md#named-location) given by the `name` parameter. Unlike [rewrite](#id5), it
does not change [$uri](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-uri). The parameter must be a name prefixed with
`@`; otherwise, the configuration is rejected.

Redirecting to a named location counts toward the same limit of 10 URI changes
used when a request URI is [rewritten](#id5).

For example, requests without a `session` cookie can be routed to a
dedicated authentication backend:

```nginx
if ($cookie_session = "") {
    goto @auth_backend;
}

location / {
    proxy_pass http://backend;
}

location @auth_backend {
    proxy_pass http://127.0.0.1:8000;
    proxy_set_header Host $host;
}
```





### if

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `if` (condition) { ... }   |
|------------------------------------------------------------------------------------------|----------------------------|
| Default                                                                                  | —                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | server, location           |

The specified condition is evaluated. If true, this module directives specified inside the braces are executed, and the request is assigned the configuration inside the if directive. Configurations inside the if directives are inherited from the previous configuration level.

#### WARNING
Although directives from other modules can be used inside the if block,
this is not recommended,
as it may lead to unexpected behavior.

A condition may be any of the following:

* a variable name; false if the value of a variable is an empty string or "0";
* comparison of a variable with a string using the "=" and "!=" operators;
* matching of a variable against a regular expression using the "~" (for case-sensitive matching) and "~\*" (for case-insensitive matching) operators. Regular expressions can contain captures that are made available for later reuse in the $1..$9 variables. Negative operators "!~" and "!~\*" are also available. If a regular expression includes the "}" or ";" characters, the whole expressions should be enclosed in single or double quotes.
* checking of a file existence with the "-f" and "!-f" operators;
* checking of a directory existence with the "-d" and "!-d" operators;
* checking of a file, directory, or symbolic link existence with the "-e" and "!-e" operators;
* checking for an executable file with the "-x" and "!-x" operators.

Examples:

```nginx
if ($http_user_agent ~ MSIE) {
    rewrite ^(.*)$ /msie/$1 break;
}

if ($http_cookie ~* "id=([^;]+)(?:;|$)") {
    set $id $1;
}

if ($request_method = POST) {
    return 405;
}

if ($slow) {
    limit_rate 10k;
}

if ($invalid_referer) {
    return 403;
}
```

#### NOTE
The value of the [$invalid_referer](https://en.angie.software//angie/docs/configuration/modules/http/http_referer.md#v-invalid-referer) built-in variable is set by the [valid_referers](https://en.angie.software//angie/docs/configuration/modules/http/http_referer.md#valid-referers) directive.





### return

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `return` code [text];

`return` code URL;

`return` URL;   |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|
| Default                                                                                  | —                                                                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | server, location, if                                                       |

Stops processing and returns the specified `code` to a client. The non-standard code 444 closes a connection without sending a response header.

It is possible to specify either a redirect URL (for codes 301, 302, 303, 307, and 308) or the response body text (for other codes). A response body text and redirect URL can contain [variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables). As a special case, a redirect URL can be specified as a URI local to this server, in which case the full redirect URL is formed according to the request scheme ($scheme) and the [server_name_in_redirect](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server-name-in-redirect) and [port_in_redirect](https://en.angie.software//angie/docs/configuration/modules/http/index.md#port-in-redirect) directives.

In addition, a URL for temporary redirect with the code 302 can be specified as the sole parameter. Such a parameter should start with the `http://`, `https://`, or "$scheme" string. A URL can contain variables.

See also the [error_page](https://en.angie.software//angie/docs/configuration/modules/http/index.md#error-page) directive.





### rewrite

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `rewrite` regex replacement [flag];   |
|------------------------------------------------------------------------------------------|---------------------------------------|
| Default                                                                                  | —                                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | server, location, if                  |

If the specified regular expression matches a request URI, URI is changed as specified in the `replacement` string. The rewrite directives are executed sequentially in order of their appearance in the configuration file. It is possible to terminate further processing of the directives using `flags`. If a `replacement` string starts with `http://`, `https://`, or "$scheme", the processing stops and the redirect is returned to a client.

The replacement string can contain variables, including the positional captures `$1` to `$9`.

An optional `flag` parameter can be one of:

| `last`      | stops processing the current set of http_rewrite module directives and starts a search for a new location matching the changed URI;     |
|-------------|-----------------------------------------------------------------------------------------------------------------------------------------|
| `break`     | stops processing the current set of http_rewrite module directives as with the break directive;                                         |
| `redirect`  | returns a temporary redirect with the 302 code; used if a `replacement` string does not start with `http://`, `https://`, or "$scheme"; |
| `permanent` | returns a permanent redirect with the 301 code.                                                                                         |

The full redirect URL is formed according to the request scheme ($scheme) and the [server_name_in_redirect](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server-name-in-redirect) and [port_in_redirect](https://en.angie.software//angie/docs/configuration/modules/http/index.md#port-in-redirect) directives.

Example:

```nginx
server {
#    ...
    rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 last;
    rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra  last;
    return  403;
#    ...
}
```

But if these directives are put inside the "/download/" location, the `last` flag should be replaced by `break`, or otherwise Angie will make 10 cycles and return the 500 error:

```nginx
location /download/ {
    rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break;
    rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra  break;
    return  403;
}
```

If a `replacement` string includes the new request arguments, the previous request arguments are appended after them. If this is undesired, putting a question mark at the end of a replacement string avoids having them appended, for example:

```nginx
rewrite ^/users/(.*)$ /show?user=$1? last;
```

If a regular expression includes the "}" or ";" characters, the whole expressions should be enclosed in single or double quotes.





### rewrite_log

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `rewrite_log` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-------------------------------|
| Default                                                                                  | `rewrite_log off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location, if    |

Enables or disables logging of http_rewrite module directives processing results into the [error_log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log) at the notice level.





### set

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `set` $variable value;   |
|------------------------------------------------------------------------------------------|--------------------------|
| Default                                                                                  | —                        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | server, location, if     |

Sets a value for the specified variable. The value can contain variables.





### uninitialized_variable_warn

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uninitialized_variable_warn` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-----------------------------------------------|
| Default                                                                                  | `uninitialized_variable_warn on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location, if                    |

Controls whether warnings about uninitialized variables are logged.



## Internal Implementation

The http_rewrite module directives are compiled at the configuration stage into internal instructions that are interpreted during request processing. An interpreter is a simple virtual stack machine.

For example, the directives

```nginx
location /download/ {
    if ($forbidden) {
        return 403;
    }

    if ($slow) {
        limit_rate 10k;
    }

    rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break;
}
```

will be translated into these instructions:

```console
variable $forbidden
check for zero
    return 403
    end of code
variable $slow
check for zero
match of regular expression
copy "/"
copy $1
copy "/mp3/"
copy $2
copy ".mp3"
end of regular expression
end of code
```

Note that there are no instructions for the [limit_rate](https://en.angie.software//angie/docs/configuration/modules/http/index.md#limit-rate) directive, since it is not related to the `http_rewrite` module. A separate configuration is created for the `if` block. If the condition is true, the request gets this configuration, where `limit_rate` equals 10k.

The directive

```nginx
rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break;
```

can be made one instruction shorter if the first slash is moved inside the parentheses in the regular expression:

```nginx
rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break;
```

The corresponding instructions will then look like this:

```console
match of regular expression
copy $1
copy "/mp3/"
copy $2
copy ".mp3"
end of regular expression
end of code
```


# https://en.angie.software/angie/docs/configuration/modules/http/http_scgi.md





# SCGI

Allows passing requests to an SCGI server.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by
default; it can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-http_scgi_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
location / {
    include   scgi_params;
    scgi_pass localhost:9000;
}
```



## Directives





### scgi_bind

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_bind` address [`transparent`] | `off`;   |
|------------------------------------------------------------------------------------------|------------------------------------------------|
| Default                                                                                  | —                                              |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                         |

Makes outgoing connections to an SCGI server originate from the specified local IP address with an optional port. Parameter value can contain [variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables). The special value `off` cancels the effect of the scgi_bind directive inherited from the previous configuration level, which allows the system to auto-assign the local IP address and port.

By default, this value is evaluated once when the request is initialized, before
an SCGI server is selected. In Angie PRO, evaluation happens after each SCGI
server selection (including retries), so the bind address can depend on the
selected server; for example, via the `$upstream_current_addr` variable.
If the evaluated value is empty, no binding is made.

The `transparent` parameter allows outgoing connections to an SCGI server
originate from a non-local IP address, for example, from a real IP address of a
client:

```nginx
scgi_bind $remote_addr transparent;
```

In order for this parameter to work, it is usually necessary to run Angie worker processes with the [superuser](https://en.angie.software//angie/docs/configuration/modules/core.md#user) privileges. On Linux it is not required as if the `transparent` parameter is specified, worker processes inherit the CAP_NET_RAW capability from the master process.

#### NOTE
It is necessary to configure kernel routing table to intercept network traffic from the SCGI server.





### scgi_buffer_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_buffer_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `scgi_buffer_size 4k|8k;`                                                                                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                            |

Sets the size of the buffer used for reading the first part of the response received from the SCGI server. This part usually contains a small response header. By default, the buffer size is equal to one memory page. This is either 4K or 8K, depending on a platform. It can be made smaller, however.





### scgi_buffering

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_buffering` `on` | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | `scgi_buffering on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location           |

Enables or disables buffering of responses from the SCGI server.

| `on`   | Angie receives a response from the SCGI server as soon as possible, saving it into the buffers set by the [scgi_buffer_size](#scgi-buffer-size) and [scgi_buffers](#scgi-buffers) directives. Sending to the client is performed in parallel: filled buffers are passed for sending, but their total size is limited by [scgi_busy_buffers_size](#scgi-busy-buffers-size). If a buffer is not completely filled, it is not passed for sending unless it contains the last part of the response. Therefore, buffered reading is not suitable when you need immediate delivery of every few bytes. If the whole response does not fit into memory, a part of it can be saved to a [temporary file](#scgi-temp-path) on the disk. Writing to temporary files is controlled by the [scgi_max_temp_file_size](#scgi-max-temp-file-size) and [scgi_temp_file_write_size](#scgi-temp-file-write-size) directives.   |
|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off`  | The response is passed to a client immediately as it is received. Angie works in a "read — send" loop and does not wait for the buffer to fill completely: for example, 10 bytes read from a 4K buffer are sent right away. At the same time, if the entire response fits into the buffer, Angie can read it in full. The maximum size of the data that Angie can receive from the server at a time is set by the [scgi_buffer_size](#scgi-buffer-size) directive. With `off`, [scgi_limit_rate](#scgi-limit-rate) does not work.                                                                                                                                                                                                                                                                                                                                                                            |

Buffering can also be enabled or disabled by passing "yes" or "no" in the `X-Accel-Buffering` response header field. This capability can be disabled using the [scgi_ignore_headers](#scgi-ignore-headers) directive.





### scgi_buffers

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_buffers` number [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `scgi_buffers 8 4k | 8k;`                                                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                               |

Sets the number and size of the buffers used for reading a response from the SCGI server, for a single connection.

By default, the buffer size is equal to one memory page. This is either 4K or 8K, depending on a platform.





### scgi_busy_buffers_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_busy_buffers_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `scgi_busy_buffers_size 8k | 16k;`                                                                                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                  |

When [buffering](#scgi-buffering) of responses from the SCGI server is enabled, limits the total size of buffers that can be busy sending a response to the client while the response is not yet fully read. In the meantime, the rest of the buffers can be used for reading the response and, if needed, buffering part of the response to a temporary file.

By default, size is limited by the size of two buffers set by the [scgi_buffer_size](#scgi-buffer-size) and [scgi_buffers](#scgi-buffers) directives.





### scgi_cache

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_cache` zone | `off`;   |
|------------------------------------------------------------------------------------------|------------------------------|
| Default                                                                                  | `scgi_cache off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location       |

Defines a shared memory zone used for caching. The same zone can be used in several places. Parameter value can contain variables.

| `off`   | disables caching inherited from the previous configuration level.   |
|---------|---------------------------------------------------------------------|

#### NOTE
When using [scgi_cache](#scgi-cache),
you typically need to also set the [scgi_cache_valid](#scgi-cache-valid) directive
to explicitly specify the caching time for responses.
If it's not set, Angie doesn't use default values
but determines the response caching time
based on HTTP response headers from the server in the following priority order:

1. The `X-Accel-Expires` header (highest priority).
2. The `Cache-Control` header
   with `max-age` or `s-maxage` parameters.
3. The `Expires` header.

If none of these headers contain valid values or are not present at all,
the response will not be cached because its expiration time cannot be determined.





### scgi_cache_background_update

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_cache_background_update` `on` | `off`;   |
|------------------------------------------------------------------------------------------|------------------------------------------------|
| Default                                                                                  | `scgi_cache_background_update off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                         |

Allows starting a background subrequest to update an expired cache item, while a stale cached response is returned to the client.

#### WARNING
Note that it is necessary to [allow](#scgi-cache-use-stale-updating) the usage of a stale cached response when it is being updated.





### scgi_cache_bypass

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_cache_bypass` string ...;   |
|------------------------------------------------------------------------------------------|-----------------------------------|
| Default                                                                                  | —                                 |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location            |

Defines conditions under which the response will not be taken from a cache. If at least one value of the string parameters is not empty and is not equal to "0" then the response will not be taken from the cache:

```nginx
scgi_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
scgi_cache_bypass $http_pragma    $http_authorization;
```

Parameter values can contain variables.

Can be used along with the [scgi_no_cache](#scgi-no-cache) directive.





### scgi_cache_key

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_cache_key` string;   |
|------------------------------------------------------------------------------------------|----------------------------|
| Default                                                                                  | —                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location     |

Defines a key for caching. The key can contain variables. For example

```nginx
scgi_cache_key localhost:9000$request_uri;
```





### scgi_cache_lock

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_cache_lock` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-----------------------------------|
| Default                                                                                  | `scgi_cache_lock off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location            |

When enabled, only one request at a time will be allowed to populate a new cache element identified according to the [scgi_cache_key](#scgi-cache-key) directive by passing a request to an SCGI server. Other requests of the same cache element will either wait for a response to appear in the cache or the cache lock for this element to be released, up to the time set by the [scgi_cache_lock_timeout](#scgi-cache-lock-timeout) directive.





### scgi_cache_lock_age

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_cache_lock_age` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `scgi_cache_lock_age 5s;`                                                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                               |

If the last request passed to the SCGI server for populating a new cache element has not completed for the specified time, one more request may be passed to the SCGI server.





### scgi_cache_lock_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_cache_lock_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `scgi_cache_lock_timeout 5s;`                                                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                   |

Sets a timeout for [scgi_cache_lock](#scgi-cache-lock). When the time expires, the request will be passed to the SCGI server, however, the response will not be cached.





### scgi_cache_max_range_offset

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_cache_max_range_offset` number;   |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| Default                                                                                  | —                                       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                  |

Sets an offset in bytes for byte-range requests. If the range is beyond the offset, the range request will be passed to the SCGI server and the response will not be cached.





### scgi_cache_methods

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_cache_methods` `GET` | `HEAD` | `POST` ...;   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------|
| Default                                                                                  | `scgi_cache_methods GET HEAD;`                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                              |

If the client request method is listed in this directive then the response will be cached. "GET" and "HEAD" methods are always added to the list, though it is recommended to specify them explicitly. See also the [scgi_no_cache](#scgi-no-cache) directive.





### scgi_cache_min_uses

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_cache_min_uses` number;   |
|------------------------------------------------------------------------------------------|---------------------------------|
| Default                                                                                  | `scgi_cache_min_uses 1;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location          |

Sets the number of requests after which the response will be cached.

#### WARNING
Cache metadata is stored in shared memory. Manually deleting cache files does
not reset the counters and may lead to unpredictable behavior. To
completely reset the cache, stop the server, delete the cache directory, and restart.

#### NOTE
Third-party cache purge modules (e.g., [Cache Purge](https://en.angie.software//angie/docs/configuration/modules/external-modules/cache-purge.md#external-cache-purge)) only delete
files but do not reset the scgi_cache_min_uses counter. The directive
is intended to protect the cache from pollution by infrequent requests, and resetting
the counter during purge may negatively affect performance.





### scgi_cache_path

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_cache_path` path [`levels=`levels] [`use_temp_path=``on` | `off`] `keys_zone=`name:size[:`file=`file] [`inactive=`time] [`max_size=`size] [`min_free=`size] [`manager_files=`number] [`manager_sleep=`time] [`manager_threshold=`time] [`loader_files=`number] [`loader_sleep=`time] [`loader_threshold=`time];   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | —                                                                                                                                                                                                                                                                                                                       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                                                                                                                                                                                                                                                                                                                    |

Sets the path and other parameters of a cache. Cache data are stored in files. The file name in a cache is a result of applying the MD5 function to the [cache key](#scgi-cache-key).

| `levels`   | defines hierarchy levels of a cache: from 1 to 3, each level accepts values 1 or 2.   |
|------------|---------------------------------------------------------------------------------------|

For example, in the following configuration:

```nginx
scgi_cache_path /data/angie/cache levels=1:2 keys_zone=one:10m;
```

file names in a cache will look like this:

```nginx
/data/angie/cache/c/29/b7f54b2df7773722d382f4809d65029c
```

A cached response is first written to a temporary file, and then the file is renamed. Temporary files and the cache can be put on different file systems. However, be aware that in this case a file is copied across two file systems instead of the cheap renaming operation. It is thus recommended that for any given location both cache and a directory holding temporary files are put on the same file system.

| `use_temp_path=on` | `off`   | determines the directory to be used for temporary files                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
|------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `on`                         | If the parameter is not specified or set to `on`, the directory specified by the [scgi_temp_path](#scgi-temp-path) directive for the given location will be used                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `off`                        | temporary files will be placed directly in the cache directory                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `keys_zone`                  | Sets the name and size of the shared memory zone for storing all active keys and information about data. Cache metadata is stored in shared memory.

The zone size is specified in bytes and must be at least two system
memory pages. The `k` and `m` suffixes are also accepted;
unlike `max_size`, this parameter does not accept `g`.

A zone of 1 megabyte is sufficient to store about 8000 keys.

When an optional file is specified with `keys_zone`,
Angie dumps the contents of this zone to disk
when the main process terminates
and attempts to restore it at the same memory address
on the next [startup](https://en.angie.software//angie/docs/configuration/runtime.md#runtime)
or after [binary upgrade](https://en.angie.software//angie/docs/configuration/runtime.md#service-upgrade),
to ensure more reliable data persistence
and reduce cache loading time.

If the zone cannot be restored due to a change in its size,
binary version incompatibility, or other reasons,
Angie will log a warning (`failed to restore zone at address`)
and will not use the zone restoration mechanism.
Instead, the incompatible file will be renamed to `.old`;
you can either delete it,
or restore its name and revert Angie to the configuration and version
in which this file was originally created.

#### WARNING
Make sure the path to the file is specified correctly
and has the necessary access permissions for Angie to use,
and is protected from unauthorized access;
relative paths are based on the [prefix](https://en.angie.software//angie/docs/installation/sourcebuild.md#paths). |
| `inactive`                   | If cached data is not accessed within the time set by this parameter, it is removed, regardless of its freshness; each access resets this timer. This differs from the size-based eviction performed by the **cache manager** described below: inactivity-based removal applies even when the cache is below `max_size`, and it ignores the validity periods configured with [scgi_cache_valid](#scgi-cache-valid).

By default, `inactive` is 10 minutes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |

A special **cache manager** process monitors the maximum cache size and the minimum amount of free space on the file system with cache and when the size is exceeded or there is not enough free space, it removes the least recently used data. The data is removed in iterations.

| `max_size`          | maximum threshold value for cache size

The value is specified in bytes; the `k`, `m`, and
`g` suffixes are also accepted.
By default, the cache size is not limited.                                                                                                                                                                                                          |
|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `min_free`          | minimum threshold value for free space on the file system with cache

The value is specified in the same units as `max_size`.
The default value `0` disables free space monitoring.

On platforms that do not support querying file system statistics,
the parameter is ignored, and Angie logs the warning
`min_free is not supported on this platform, ignored`. |
| `manager_files`     | limits the number of items to be deleted during one iteration

By default, `100`                                                                                                                                                                                                                                                                                                       |
| `manager_threshold` | limits the duration of one iteration

By default, `200` milliseconds                                                                                                                                                                                                                                                                                                                   |
| `manager_sleep`     | configures a pause between iterations

By default, `50` milliseconds                                                                                                                                                                                                                                                                                                                   |

A minute after Angie starts, the special **cache loader** process is activated. It loads information about previously cached data stored on file system into a cache zone. The loading is also done in iterations.

| `loader_files`     | limits the number of items to load during one iteration

By default, `100`   |
|--------------------|--------------------------------------------------------------------------------------|
| `loader_threshold` | limits the duration of one iteration

By default, `200` milliseconds         |
| `loader_sleep`     | configures a pause between iterations

By default, `50` milliseconds         |





### scgi_cache_revalidate

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_cache_revalidate` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| Default                                                                                  | `scgi_cache_revalidate off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                  |

Enables revalidation of expired cache items using conditional requests with the `If-Modified-Since`  and `If-None-Match`  header fields.





### scgi_cache_use_stale

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_cache_use_stale` `error` | `timeout` | `invalid_header` | `updating` | `http_500` | `http_503` | `http_403` | `http_404` | `http_429` | `off` ...;   |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `scgi_cache_use_stale off;`                                                                                                                                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                                                     |

Determines in which cases a stale cached response can be used. The directive's parameters match the parameters of the [scgi_next_upstream](#scgi-next-upstream) directive.

| `error`    | permits using a stale cached response if a SCGI server to process a request cannot be selected.                                                                                        |
|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `updating` | additional parameter, permits using a stale cached response if it is currently being updated. This allows minimizing the number of accesses to SCGI servers when updating cached data. |

Using a stale cached response can also be enabled directly in the response header for a specified number of seconds after the response became stale:

* The [stale-while-revalidate](https://datatracker.ietf.org/doc/html/rfc5861#section-3) extension of the `Cache-Control` header field permits using a stale cached response if it is currently being updated.
* The [stale-if-error](https://datatracker.ietf.org/doc/html/rfc5861#section-4) extension of the `Cache-Control` header field permits using a stale cached response in case of an error.

#### NOTE
This method has lower priority than setting parameters using the directive.

To minimize the number of accesses to SCGI servers when populating a new cache element, the [scgi_cache_lock](#scgi-cache-lock) directive can be used.





### scgi_cache_valid

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_cache_valid` [code ...] [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | —                                                                                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                       |

Sets caching time for different response codes. For example, the following directives

```nginx
scgi_cache_valid 200 302 10m;
scgi_cache_valid 404      1m;
```

set 10 minutes of caching for responses with codes 200 and 302 and 1 minute for responses with code 404.

If only caching time is specified,

```nginx
scgi_cache_valid 5m;
```

then only 200, 301, and 302 responses are cached.

In addition, it can be specified to cache any responses using the `any` parameter:

```nginx
scgi_cache_valid 200 302 10m;
scgi_cache_valid 301      1h;
scgi_cache_valid any      1m;
```

#### NOTE
Parameters of caching can also be set directly in the response header. This has higher priority than setting caching time using the directive.

* The `X-Accel-Expires` header field sets caching time of a response in seconds. The zero value disables caching for a response. If the value starts with the @ prefix, it sets an absolute time in seconds since Epoch, up to which the response may be cached.
* If the header does not include the `X-Accel-Expires` field, parameters of caching may be set in the header fields `Expires` or `Cache-Control`.
* If the header includes the `Set-Cookie` field, such a response will not be cached.
* If the header includes the `Vary` field with the special value "\*", such a response will not be cached. If the header includes the `Vary` field with another value, such a response will be cached taking into account the corresponding request header fields.

Processing of one or more of these response header fields can be disabled using the [scgi_ignore_headers](#scgi-ignore-headers) directive.





### scgi_connect_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_connect_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `scgi_connect_timeout 60s;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                |

Defines a timeout for establishing a connection with an SCGI server. It should be noted that this timeout cannot usually exceed 75 seconds.





### scgi_connection_drop

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_connection_drop` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units) | `on` | `off`;   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `scgi_connection_drop off;`                                                                                                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                               |

Enables termination of all active connections to the proxied server after it has been
removed from the group or marked as permanently unavailable by a [reresolve](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve) process or the [API command](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-config-methods)
`DELETE`.
Idle connections in the [cache](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive) are not affected.

A connection is terminated when the next read or write event is processed for
either the client or the proxied server.

Setting time enables a connection termination [timeout](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);
with `on` set, connections are dropped immediately.





### scgi_force_ranges

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_force_ranges` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-------------------------------------|
| Default                                                                                  | `scgi_force_ranges off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location              |

Enables byte-range support for both cached and uncached responses from the SCGI server regardless of the `Accept-Ranges` field in these responses.





### scgi_hide_header

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_hide_header` field;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| Default                                                                                  | —                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location      |

By default, Angie does not pass the header fields `Status` and `X-Accel-...` from the response of an SCGI server to a client. The `scgi_hide_header` directive sets additional fields that will not be passed. If, conversely, the passing of fields needs to be permitted, the [scgi_pass_header](#scgi-pass-header) directive can be used.





### scgi_ignore_client_abort

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_ignore_client_abort` `on` | `off`;   |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| Default                                                                                  | `scgi_ignore_client_abort off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                     |

Determines whether the connection with an SCGI server should be closed when a client closes the connection without waiting for a response.





### scgi_ignore_headers

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_ignore_headers` field ...;   |
|------------------------------------------------------------------------------------------|------------------------------------|
| Default                                                                                  | —                                  |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location             |

Disables processing of certain response header fields from the SCGI server. The following fields can be ignored: `X-Accel-Redirect`, `X-Accel-Expires`, `X-Accel-Limit-Rate`, `X-Accel-Buffering`, `X-Accel-Charset`, `Expires`, `Cache-Control`, `Set-Cookie`, and `Vary`.

If not disabled, processing of these header fields has the following effect:

* `X-Accel-Expires`, `Expires`, `Cache-Control`, `Set-Cookie`, and `Vary` set the parameters of response [caching](#scgi-cache-valid);
* `X-Accel-Redirect` performs an [internal redirect](https://en.angie.software//angie/docs/configuration/modules/http/index.md#internal) to the specified URI;
* `X-Accel-Limit-Rate` sets the [rate limit](https://en.angie.software//angie/docs/configuration/modules/http/index.md#limit-rate) for transmission of a response to a client;
* `X-Accel-Buffering` enables or disables [buffering](#scgi-buffering) of a response;
* `X-Accel-Charset` sets the desired [charset](https://en.angie.software//angie/docs/configuration/modules/http/http_charset.md#id1) of a response.





### scgi_intercept_errors

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_intercept_errors` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| Default                                                                                  | `scgi_intercept_errors off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                  |

Determines whether SCGI server responses with codes greater than or equal to 300 should be passed to a client or be intercepted and redirected to Angie for processing with the [error_page](https://en.angie.software//angie/docs/configuration/modules/http/index.md#error-page) directive.





### scgi_limit_rate

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_limit_rate` rate;   |
|------------------------------------------------------------------------------------------|---------------------------|
| Default                                                                                  | `scgi_limit_rate 0;`      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location    |

Limits the speed of reading the response from the SCGI server.
The rate is specified in bytes per second and can contain variables.

| `0`   | disables rate limiting   |
|-------|--------------------------|

#### NOTE
The limit is set per a request, and so if Angie simultaneously opens two connections to the SCGI server, the overall rate will be twice as much as the specified limit. The limitation works only if [buffering](#scgi-buffering) of responses from the SCGI server is enabled.





### scgi_max_temp_file_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_max_temp_file_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `scgi_max_temp_file_size 1024m;`                                                                                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                   |

When [buffering](#scgi-buffering) of responses from the SCGI server is enabled, and the whole response does not fit into the buffers set by the [scgi_buffer_size](#scgi-buffer-size) and [scgi_buffers](#scgi-buffers) directives, a part of the response can be saved to a temporary file. This directive sets the maximum size of the temporary file. The size of data written to the temporary file at a time is set by the [scgi_temp_file_write_size](#scgi-temp-file-write-size) directive.

| `0`   | disables buffering of responses to temporary files   |
|-------|------------------------------------------------------|

#### NOTE
This restriction does not apply to responses that will be [cached](#scgi-cache) or [stored](#scgi-store) on disk.





### scgi_next_upstream

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_next_upstream` `error` | `timeout` | `invalid_header` | `http_500` | `http_503` | `http_403` | `http_404` | `http_429` | `non_idempotent` | `off` ...;   |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `scgi_next_upstream error timeout;`                                                                                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                                                         |

Specifies in which cases a request should be passed to the next server:

| `error`          | an error occurred while establishing a connection with the server, passing a request to it, or reading the response header;                                                                                                                                                                             |
|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `timeout`        | a timeout has occurred while establishing a connection with the server, passing a request to it, or reading the response header;                                                                                                                                                                        |
| `invalid_header` | a server returned an empty or invalid response;                                                                                                                                                                                                                                                         |
| `http_500`       | a server returned a response with the code 500;                                                                                                                                                                                                                                                         |
| `http_503`       | a server returned a response with the code 503;                                                                                                                                                                                                                                                         |
| `http_403`       | a server returned a response with the code 403;                                                                                                                                                                                                                                                         |
| `http_404`       | a server returned a response with the code 404;                                                                                                                                                                                                                                                         |
| `http_429`       | a server returned a response with the code 429;                                                                                                                                                                                                                                                         |
| `non_idempotent` | normally, requests with a [non-idempotent](https://datatracker.ietf.org/doc/html/rfc7231#section-4.2.2) method
(`POST`, `LOCK`, `PATCH`) are not passed to the next
server if a request has been sent to an upstream server; enabling this
option explicitly allows retrying such requests; |
| `off`            | disables passing a request to the next server.                                                                                                                                                                                                                                                          |

#### NOTE
One should bear in mind that passing a request to the next server is only possible if nothing has been sent to a client yet. That is, if an error or timeout occurs in the middle of the transferring of a response, fixing this is impossible.

The directive also defines what is considered an [unsuccessful attempt](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) of communication with a server.

| `error`

`timeout`

`invalid_header`   | are always considered unsuccessful attempts, even if they are not specified in the directive   |
|--------------------------------------------------------|------------------------------------------------------------------------------------------------|
| `http_500`

`http_503`

`http_429`     | are considered unsuccessful attempts only if they are specified in the directive               |
| `http_403`

`http_404`                         | are never considered unsuccessful attempts                                                     |

Passing a request to the next server can be limited by the [number of tries](#scgi-next-upstream-tries) and by [time](#scgi-next-upstream-timeout).





### scgi_next_upstream_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_next_upstream_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `scgi_next_upstream_timeout 0;`                                                                                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                      |

Limits the time during which a request can be passed to the [next](#scgi-next-upstream) server.

| `0`   | turns off this limitation   |
|-------|-----------------------------|





### scgi_next_upstream_tries

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_next_upstream_tries` number;   |
|------------------------------------------------------------------------------------------|--------------------------------------|
| Default                                                                                  | `scgi_next_upstream_tries 0;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location               |

Limits the number of possible tries for passing a request to the [next](#scgi-next-upstream) server.

| `0`   | turns off this limitation   |
|-------|-----------------------------|





### scgi_no_cache

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_no_cache` string ...;   |
|------------------------------------------------------------------------------------------|-------------------------------|
| Default                                                                                  | —                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location        |

Defines conditions under which the response will not be saved to a cache. If at least one value of the string parameters is not empty and is not equal to "0" then the response will not be saved:

```nginx
scgi_no_cache $cookie_nocache $arg_nocache$arg_comment;
scgi_no_cache $http_pragma    $http_authorization;
```

Parameter values can contain variables.

Can be used along with the [scgi_cache_bypass](#scgi-cache-bypass) directive.





### scgi_param

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_param` parameter value [`if_not_empty`];   |
|------------------------------------------------------------------------------------------|--------------------------------------------------|
| Default                                                                                  | —                                                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                           |

Sets a parameter that should be passed to the SCGI server. The value can contain variables. These directives are inherited from the previous configuration level if and only if there are no scgi_param directives defined on the current level.

Standard [CGI environment variables](https://datatracker.ietf.org/doc/html/rfc3875#section-4.1) should be provided as SCGI headers, see the scgi_params file provided in the distribution:

```nginx
location / {
    include scgi_params;
#    ...
}
```

In the standard `scgi_params` file, `REQUEST_METHOD` is set to
`$upstream_request_method`.

If the directive is specified with `if_not_empty` then such a parameter will be passed to the server only if its value is not empty:

```nginx
scgi_param HTTPS $https if_not_empty;
```





### scgi_pass

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_pass` uri;         |
|------------------------------------------------------------------------------------------|--------------------------|
| Default                                                                                  | —                        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | location, if in location |

Sets the address of an SCGI server. The address can be specified as a domain name or IP address, and an optional port:

```nginx
scgi_pass localhost:9000;
```

or as a UNIX domain socket path:

```nginx
scgi_pass unix:/tmp/scgi.socket;
```

If a domain name resolves to several addresses, all of them will be used in a round-robin fashion. In addition, an address can be specified as a [server group](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream).

Parameter value can contain variables. In this case, if an address is specified as a domain name, the name is searched among the described server groups, and, if not found, is determined using a [resolver](https://en.angie.software//angie/docs/configuration/modules/http/index.md#resolver).

#### NOTE
If `scgi_pass` is specified in a `location` with a trailing slash in the prefix
(for example, `location /name/`),
and the [auto_redirect](https://en.angie.software//angie/docs/configuration/modules/http/index.md#auto-redirect) directive is set to `default`,
requests without a trailing slash will be redirected (`/name -> /name/`).





### scgi_pass_header

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_pass_header` field ...;   |
|------------------------------------------------------------------------------------------|---------------------------------|
| Default                                                                                  | —                               |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location          |

Permits passing [otherwise disabled](#scgi-hide-header) header fields from a SCGI server to a client.





### scgi_pass_request_body

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_pass_request_body` `on` | `off`;   |
|------------------------------------------------------------------------------------------|------------------------------------------|
| Default                                                                                  | `scgi_pass_request_body on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                   |

Indicates whether the original request body is passed to the SCGI server. See also the [scgi_pass_request_headers](#scgi-pass-request-headers) directive.





### scgi_pass_request_headers

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_pass_request_headers` `on` | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| Default                                                                                  | `scgi_pass_request_headers on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                      |

Indicates whether the header fields of the original request are passed to the SCGI server. See also the [scgi_pass_request_body](#scgi-pass-request-body) directive.





### scgi_read_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_read_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `scgi_read_timeout 60s;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                             |

Defines a timeout for reading a response from the SCGI server. The timeout is set only between two successive read operations, not for the transmission of the whole response. If the SCGI server does not transmit anything within this time, the connection is closed.





### scgi_request_buffering

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_request_buffering` `on` | `off`;   |
|------------------------------------------------------------------------------------------|------------------------------------------|
| Default                                                                                  | `scgi_request_buffering on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                   |

Enables or disables buffering of a client request body.

| `on`   | the request body is fully [read](https://en.angie.software//angie/docs/configuration/modules/http/index.md#client-body-buffer-size) from the client before sending the request to an SCGI server.                      |
|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off`  | the request body is sent to the SCGI server immediately as it is received. In this case, the request cannot be passed to the [next server](#scgi-next-upstream) if Angie has already started sending the request body. |

When HTTP/1.1 chunked transfer encoding is used to send the original request body, the request body will be buffered regardless of the directive value.





### scgi_send_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_send_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `scgi_send_timeout 60s;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                             |

Sets a timeout for transmitting a request to the SCGI server. The timeout is set only between two successive write operations, not for the transmission of the whole request. If the SCGI server does not receive anything within this time, the connection is closed.





### scgi_socket_keepalive

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_socket_keepalive` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| Default                                                                                  | `scgi_socket_keepalive off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                  |

Configures the "TCP keepalive" behavior for outgoing connections to a SCGI server.

| `off`   | By default, the operating system's settings are in effect for the socket.   |
|---------|-----------------------------------------------------------------------------|
| `on`    | The SO_KEEPALIVE socket option is turned on for the socket.                 |





### scgi_store

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_store` `on` | `off` | string;   |
|------------------------------------------------------------------------------------------|---------------------------------------|
| Default                                                                                  | `scgi_store off;`                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                |

Enables saving of files to a disk.

| `on`   | saves files with paths corresponding to the directives [alias](https://en.angie.software//angie/docs/configuration/modules/http/index.md#alias) or [root](https://en.angie.software//angie/docs/configuration/modules/http/index.md#root)   |
|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off`  | disables saving of files                                                                                                                                                                                                                    |

The file name can be set explicitly using the string with variables:

```nginx
scgi_store /data/www$original_uri;
```

The modification time of files is set according to the received `Last-Modified` response header field. The response is first written to a temporary file, and then the file is renamed. Temporary files and the persistent store can be put on different file systems. However, be aware that in this case a file is copied across two file systems instead of the cheap renaming operation. It is thus recommended that for any given location both saved files and a directory holding temporary files, set by the [scgi_temp_path](#scgi-temp-path) directive, are put on the same file system.

This directive can be used to create local copies of static unchangeable files, e.g.:

```nginx
location /images/ {
    root              /data/www;
    error_page        404 = /fetch$uri;
}

location /fetch/ {
    internal;

    scgi_pass         backend:9000;
    ...

    scgi_store        on;
    scgi_store_access user:rw group:rw all:r;
    scgi_temp_path    /data/temp;

    alias             /data/www/;
}
```





### scgi_store_access

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_store_access` users:permissions ...;   |
|------------------------------------------------------------------------------------------|----------------------------------------------|
| Default                                                                                  | `scgi_store_access user:rw;`                 |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                       |

Sets access permissions for newly created files and directories, e.g.:

```nginx
scgi_store_access user:rw group:rw all:r;
```

If any `group` or `all` access permissions are specified then user
permissions may be omitted:

```nginx
scgi_store_access group:rw all:r;
```





### scgi_temp_file_write_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_temp_file_write_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `scgi_temp_file_write_size 8k|16k;`                                                                                        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                     |

Limits the size of data written to a temporary file at a time, when buffering of responses from the SCGI server to temporary files is enabled. By default, size is limited by two buffers set by the [scgi_buffer_size](#scgi-buffer-size) and [scgi_buffers](#scgi-buffers) directives. The maximum size of a temporary file is set by the [scgi_max_temp_file_size](#scgi-max-temp-file-size) directive.





### scgi_temp_path

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `scgi_temp_path` path [level1 [level2 [level3]]]\`;                                                                                                                       |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `scgi_temp_path scgi_temp;`
(the path depends on the `--http-scgi-temp-path` [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#paths)) |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                                                                    |

Defines a directory for storing temporary files with data received from SCGI servers. Up to three-level subdirectory hierarchy can be used underneath the specified directory. For example, in the following configuration

```nginx
scgi_temp_path /spool/angie/scgi_temp 1 2;
```

a temporary file might look like this:

```nginx
/spool/angie/scgi_temp/7/45/00000123457
```

See also the `use_temp_path` parameter of the [scgi_cache_path](#scgi-cache-path) directive.


# https://en.angie.software/angie/docs/configuration/modules/http/http_secure_link.md





# Secure Link

The module allows checking authenticity of requested links, protecting resources from unauthorized access, and limiting link lifetime.

The authenticity of a requested link is verified by comparing the checksum value passed in a request with the value computed for the request. If a link has a limited lifetime and the time has expired, the link is considered outdated. The status of these checks is made available in the [$secure_link](#v-secure-link) variable.

The module implements two alternative operation modes. The first mode is enabled by the [secure_link_secret](#secure-link-secret) directive and allows checking authenticity of requested links and protecting them from unauthorized access. The second mode is enabled by the [secure_link](#id1) and [secure_link_md5](#secure-link-md5) directives and also allows limiting link lifetime.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module isn't built
by default; it must be enabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--with-http_secure_link_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Directives





### secure_link

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `secure_link` expression;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| Default                                                                                  | —                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location      |

Defines a [string with variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables) from which the checksum value and the link's expiration time will be extracted.

Variables used in an expression are usually associated with a request; see [example](#secure-link-md5) below.

The checksum value extracted from the string is compared with the MD5 hash value of the expression defined by the [secure_link_md5](#secure-link-md5) directive.

If the checksums do not match, the [$secure_link](#v-secure-link) variable is set to an empty string. If the checksums match, the link lifetime is checked.

If the link has a limited lifetime and the time has expired, the [$secure_link](#v-secure-link) variable is set to `0`. Otherwise, it is set to `1`. The MD5 hash value passed in a request is encoded in base64url.

If a link has a limited lifetime, the expiration time is set in seconds since Epoch (January 1, 1970 00:00:00 GMT). The value is specified in the expression after the MD5 hash, and is separated by a comma. The expiration time passed in a request is available through the [$secure_link_expires](#v-secure-link-expires) variable for use in the [secure_link_md5](#secure-link-md5) directive. If the expiration time is not specified, a link has unlimited lifetime.





### secure_link_md5

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `secure_link_md5` expression;   |
|------------------------------------------------------------------------------------------|---------------------------------|
| Default                                                                                  | —                               |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location          |

Defines an expression for which the MD5 hash value will be computed and compared with the value passed in a request. The expression can contain variables.

The expression should contain the secured part of a link (resource) and a secret ingredient. If the link has a limited lifetime, the expression should also contain [$secure_link_expires](#v-secure-link-expires).

To prevent unauthorized access, the expression may contain some information about the client, such as its address and browser version.

Example:

```nginx
location /s/ {
    secure_link $arg_md5,$arg_expires;
    secure_link_md5 "$secure_link_expires$uri$remote_addr secret";

    if ($secure_link = "") {
        return 403;
    }

    if ($secure_link = "0") {
        return 410;
    }

#    ...
}
```

The "/s/link?md5=_e4Nc3iduzkWRm01TBBNYw&expires=2147483647" link restricts access to "/s/link" for the client with the IP address 127.0.0.1. The link also has limited lifetime until January 19, 2038 (GMT).

On UNIX, the md5 request argument value can be obtained as:

```console
$ echo -n '2147483647/s/link127.0.0.1 secret' | \
   openssl md5 -binary | openssl base64 | tr +/ -_ | tr -d =
```





### secure_link_secret

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `secure_link_secret` word;   |
|------------------------------------------------------------------------------------------|------------------------------|
| Default                                                                                  | —                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | location                     |

Defines a secret word used to check authenticity of requested links.

The full URI of a requested link looks as follows:

```console
/prefix/hash/link
```

where hash is a hexadecimal representation of the MD5 hash computed for the concatenation of the link and secret word, and prefix is an arbitrary string without slashes.

If the requested link passes the authenticity check, the [$secure_link](#v-secure-link) variable is set to the link extracted from the request URI. Otherwise, the [$secure_link](#v-secure-link) variable is set to an empty string.

Example:

```nginx
location /p/ {
    secure_link_secret secret;

    if ($secure_link = "") {
        return 403;
    }

    rewrite ^ /secure/$secure_link;
}

location /secure/ {
    internal;
}
```

A request of "/p/5e814704a28d9bc1914ff19fa0c4a00a/link" will be internally redirected to "/secure/link".

On UNIX, the hash value for this example can be obtained as:

```console
$ echo -n 'linksecret' | openssl md5 -hex
```



## Built-in Variables



### `$secure_link`

The status of a link check. The specific value depends on the selected operation mode.



### `$secure_link_expires`

The expiration time of a link in seconds since Epoch, passed in a request; intended to be used only in the [secure_link_md5](#secure-link-md5) directive.


# https://en.angie.software/angie/docs/configuration/modules/http/http_slice.md





# Slice

The module is a filter that splits a request into subrequests, each returning a certain range of response. The filter provides more effective caching of large responses.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module isn't built
by default; it must be enabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--with-http_slice_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
location / {
    slice             1m;
    proxy_cache       cache;
    proxy_cache_key   $uri$is_args$args$slice_range;
    proxy_set_header  Range $slice_range;
    proxy_cache_valid 200 206 1h;
    proxy_pass        http://localhost:8000;
}
```

In this example, the response is split into 1-megabyte cacheable slices.



## Directives





### slice

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `slice` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `slice 0;`                                                                                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                 |

Sets the size of the slice. The zero value disables splitting responses into slices.

#### WARNING
Note that a too low value may result in excessive memory usage and opening a large number of files.

In order for a subrequest to return the required range, the [$slice_range](#v-slice-range) variable should be passed to the proxied server as the `Range` request header field. If [caching](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache) is enabled, [$slice_range](#v-slice-range) should be added to the [cache key](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-key) and caching of responses with 206 status code should be [enabled](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-valid).



## Built-in Variables



### `$slice_range`

The current slice range in [HTTP byte range](https://datatracker.ietf.org/doc/html/rfc7233#section-2.1) format, for example, `bytes=0-1048575`.


# https://en.angie.software/angie/docs/configuration/modules/http/http_split_clients.md





# Split Clients

The module generates variables for A/B testing, canary releases, and other scenarios
that direct a certain percentage of clients to one server or configuration
while routing the rest elsewhere.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by
default; it can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-http_split_clients_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
http {
    split_clients "${remote_addr}AAA" $variant {
                   0.5%               .one;
                   2.0%               .two;
                   *                  "";
    }

    server {
        location / {
            index index${variant}.html;
```



## Directives





### split_clients

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `split_clients` string $variable { ... }   |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| Default                                                                                  | —                                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                                       |

Creates a $variable by hashing the string;
[variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables) in the string are substituted,
the result is hashed,
then the hash value is used to select the string value of the $variable.

The hash function uses
[MurmurHash2](https://en.wikipedia.org/wiki/MurmurHash#MurmurHash2)
(32-bit),
and its entire value range
(0 to 4294967295)
is mapped to buckets in order of appearance;
the percentages determine the size of the buckets.
A wildcard (`*`) may occur last;
hashes that don't fall into other buckets are mapped to its assigned value.

Example:

```nginx
split_clients "${remote_addr}AAA" $variant {
               0.5%               .one;
               2.0%               .two;
               *                  "";
}
```

Here, after substitution in the `$*remote_addr*AAA` string,
the hash values are distributed as follows:

- values from 0 to 21474835 (0.5%) yield `.one`;
- values from 21474836 to 107374180 (2%) yield `.two`;
- values from 107374181 to 4294967295 (all others) yield `""`
  (empty string).


# https://en.angie.software/angie/docs/configuration/modules/http/http_ssi.md





# SSI

The module is a filter that processes SSI (Server Side Includes) commands in responses passing through it.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by
default; it can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-http_ssi_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
location / {
    ssi on;
#    ...
}
```



## Directives





### ssi

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssi` `on` | `off`;                    |
|------------------------------------------------------------------------------------------|----------------------------------------|
| Default                                                                                  | `ssi off;`                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location, if in location |

Enables or disables processing of SSI commands in responses.





### ssi_last_modified

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssi_last_modified` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-------------------------------------|
| Default                                                                                  | `ssi_last_modified off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location              |

Allows preserving the `Last-Modified` header field from the original response during SSI processing to facilitate response caching.

By default, the header field is removed as contents of the response are modified during processing and may contain dynamically generated elements or parts that are changed independently of the original response.





### ssi_min_file_chunk

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssi_min_file_chunk` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `ssi_min_file_chunk 1k;`                                                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                              |

Sets the minimum size for parts of a response stored on disk, starting from which it makes sense to send them using [sendfile](https://en.angie.software//angie/docs/configuration/modules/http/index.md#sendfile).





### ssi_silent_errors

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssi_silent_errors` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-------------------------------------|
| Default                                                                                  | `ssi_silent_errors off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location              |

If enabled, suppresses the output of the "[an error occurred while processing the directive]" string if an error occurred during SSI processing.





### ssi_types

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssi_types` mime-type ...;   |
|------------------------------------------------------------------------------------------|------------------------------|
| Default                                                                                  | `ssi_types text/html;`       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location       |

Enables processing of SSI commands in responses with the specified MIME types in addition to `text/html`. The special value "\*" matches any MIME type.





### ssi_value_length

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssi_value_length` length;   |
|------------------------------------------------------------------------------------------|------------------------------|
| Default                                                                                  | `ssi_value_length 256;`      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location       |

Sets the maximum length of parameter values in SSI commands.



## SSI Commands

SSI commands have the following generic format:

```html

```

The following commands are supported:



### `block`

Defines a block that can be used as a stub in the include command. The block can contain other SSI commands. The command has the following parameter:



#### `name`

block name.

Example:

```html

stub

```



### `config`

Sets some parameters used during SSI processing, namely:



#### `errmsg`

a string that is output if an error occurs during SSI processing. By default, the following string is output:

```none
`[an error occurred while processing the directive]`
```



#### `timefmt`

a format string passed to the `strftime()` function used to output date and time. By default, the following format is used:

```none
`"%A, %d-%b-%Y %H:%M:%S %Z"`
```

The "%s" format is suitable to output time in seconds.



### `echo`

Outputs the value of a variable. The command has the following parameters:



#### `var`

the variable name.



#### `encoding`

the encoding method. Possible values include `none`, `url`, and `entity`. By default, `entity` is used.



#### `default`

a non-standard parameter that sets a string to be output if a variable is undefined. By default, `(none)` is output.

The command

```html

```

replaces the following sequence of commands:

```html
no
```



### `if`

Performs a conditional inclusion. The following commands are supported:

```html

...

...

...

```

Only one level of nesting is currently supported. The command has the following parameter:



#### `expr`

expression. An expression can be:

* variable existence check:

```html

```

* comparison of a variable with a text:

```html


```

* comparison of a variable with a regular expression:

```html


```

If a text contains variables, their values are substituted. A regular expression can contain positional and named captures that can later be used through variables, for example:

```html

  
  

```



### `include`

Includes the result of another request into a response. The command has the following parameters:



#### `file`

specifies an included file, for example:

```html

```



#### `virtual`

specifies an included request, for example:

```html

```

Several requests specified on one page and processed by proxied or FastCGI/uwsgi/SCGI/gRPC servers run in parallel. If sequential processing is desired, the wait parameter should be used.



#### `stub`

a non-standard parameter that names the block whose content will be output if the included request results in an empty body or if an error occurs during the request processing, for example:

```html
 

```

The replacement block content is processed in the included request context.



#### `wait`

a non-standard parameter that instructs to wait for a request to fully complete before continuing with SSI processing, for example:

```html

```



#### `set`

a non-standard parameter that instructs to write a successful result of request processing to the specified variable, for example:

```html

```

The maximum size of the response is set by the [subrequest_output_buffer_size](https://en.angie.software//angie/docs/configuration/modules/http/index.md#subrequest-output-buffer-size) directive:

```nginx
location /remote/ {
    subrequest_output_buffer_size 64k;
#    ...
}
```



### `set`

Sets a value of a variable. The command has the following parameters:

#### `var`

the variable name.



#### `value`

the variable value. If an assigned value contains variables, their values are substituted.



## Built-in Variables



### `$date_gmt`

current time in GMT. The format is set by the config command with the timefmt parameter.



### `$date_local`

current time in the local time zone. The format is set by the config command with the timefmt parameter.


# https://en.angie.software/angie/docs/configuration/modules/http/http_ssl.md






# SSL

Provides the necessary support for HTTPS.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module isn't built
by default; it must be enabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--with-http_ssl_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.

#### NOTE
This module requires the OpenSSL library.



## Configuration Example

To reduce the processor load it is recommended to

* set the number of [worker processes](https://en.angie.software//angie/docs/configuration/modules/core.md#worker-processes) equal to the number of processors,
* enable [keep-alive](https://en.angie.software//angie/docs/configuration/modules/http/index.md#keepalive-timeout) connections,
* enable the [shared](#ssl-session-cache) session cache,
* disable the [built-in](#ssl-session-cache) session cache,
* and possibly increase the session [lifetime](#ssl-session-timeout) (by default, 5 minutes):

```nginx
worker_processes auto;

http {

    # ...

    server {
        listen              443 ssl;
        keepalive_timeout   70;

        ssl_protocols       TLSv1.2 TLSv1.3;
        ssl_ciphers         AES128-SHA:AES256-SHA:RC4-SHA:DES-CBC3-SHA:RC4-MD5;
        ssl_certificate     /usr/local/angie/conf/cert.pem;
        ssl_certificate_key /usr/local/angie/conf/cert.key;
        ssl_session_cache   shared:SSL:10m;
        ssl_session_timeout 10m;

        # ...
    }
```



## Directives





### ssl_buffer_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_buffer_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `ssl_buffer_size 16k;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                                                                                                     |

Sets the size of the buffer used for sending data.

By default, the buffer size is 16k, which corresponds to minimal overhead when sending big responses. To minimize Time To First Byte it may be beneficial to use smaller values, for example:

```nginx
ssl_buffer_size 4k;
```





### ssl_certificate

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_certificate` file;   |
|------------------------------------------------------------------------------------------|---------------------------|
| Default                                                                                  | —                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server              |

Specifies a file with the certificate in the PEM format for the given virtual server. If intermediate certificates should be specified in addition to a primary certificate, they should be specified in the same file in the following order: the primary certificate comes first, then the intermediate certificates. A secret key in the PEM format may be placed in the same file.

This directive can be specified multiple times to load certificates of different types, for example, RSA and ECDSA:

```nginx
server {
    listen              443 ssl;
    server_name         example.com;

    ssl_certificate     example.com.rsa.crt;
    ssl_certificate_key example.com.rsa.key;

    ssl_certificate     example.com.ecdsa.crt;
    ssl_certificate_key example.com.ecdsa.key;

    # ...
}
```

Only OpenSSL 1.0.2 or higher supports separate certificate chains for different certificates. With older versions, only one certificate chain can be used.

#### NOTE
The file name can contain [variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables) when using OpenSSL 1.0.2 or higher:

```nginx
ssl_certificate     $ssl_server_name.crt;
ssl_certificate_key $ssl_server_name.key;
```

Note that using variables implies that a certificate will be loaded for each SSL handshake, and this may have a negative impact on performance.

The value `data:$variable` can be specified instead of the file, which loads a certificate from a variable without using intermediate files. Note that inappropriate use of this syntax may have its security implications, such as writing secret key data to [error log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log).

#### NOTE
> It should be kept in mind that due to the HTTPS protocol limitations for maximum interoperability virtual servers should listen on [different IP addresses](https://en.angie.software//angie/docs/configuration/ssl.md#https-separate-ips).

If [ssl_ntls](#ssl-ntls) is enabled, the directive can accept two arguments
(the signature and the encryption parts of the certificate)
instead of one:

```nginx
listen ... ssl;

ssl_ntls  on;

# dual NTLS certificate
ssl_certificate      sign.crt enc.crt;
ssl_certificate_key  sign.key enc.key;

# can be used together with a regular RSA certificate
ssl_certificate  rsa.crt;
ssl_certificate_key rsa.key;
```





### ssl_certificate_cache

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_certificate_cache` `off`;

`ssl_certificate_cache` `max=`N [`inactive=`time] [`valid=`time];   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `ssl_certificate_cache off;`                                                                                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                                                                                                |

Defines a cache that stores [SSL certificates](#ssl-certificate) and [secret keys](#ssl-certificate-key) specified using variables.

The directive supports the following parameters:

- `max` — sets the maximum number of elements in the cache. When the cache
  overflows, the least recently used (LRU) elements are removed.
- `inactive` — defines the time after which an element is removed if it
  has not been accessed during this time, even if still within its
  `valid` period; each access resets this timer. The default is 10
  seconds.
- `valid` — defines the time during which a cached element is considered
  valid and can be reused. The default is 60 seconds. After this period,
  certificates are reloaded or revalidated.
- `off` — disables the cache.

Example:

```nginx
ssl_certificate       $ssl_server_name.crt;
ssl_certificate_key   $ssl_server_name.key;
ssl_certificate_cache max=1000 inactive=20s valid=1m;
```





### ssl_certificate_compression

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_certificate_compression` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-----------------------------------------------|
| Default                                                                                  | `ssl_certificate_compression off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                                  |

Enables TLS 1.3 [compression](https://datatracker.ietf.org/doc/html/rfc8879) of server certificates.

#### NOTE
The directive is supported when using OpenSSL 3.2 or higher; the list of supported compression algorithms is provided by the library.

#### NOTE
The directive is supported when using [BoringSSL](https://boringssl.googlesource.com/boringssl/); the list of supported compression algorithms includes `zlib`.

If [ssl_stapling](#ssl-stapling) is enabled, certificate compression is disabled.





### ssl_certificate_key

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_certificate_key` file;   |
|------------------------------------------------------------------------------------------|-------------------------------|
| Default                                                                                  | —                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                  |

Specifies a file with the secret key in the PEM format for the given virtual server.

#### NOTE
The file name can contain variables when using OpenSSL 1.0.2 or higher.

The value `engine:name:id` can be specified instead of the file, which loads a secret key with a specified id from the OpenSSL engine name.

The value `store:scheme:id` can be specified instead of the file, which is used to load a secret key with a specified id and OpenSSL provider registered URI scheme, such as [pkcs11](https://datatracker.ietf.org/doc/html/rfc7512).

The value `data:$variable` can be specified instead of the file, which loads a secret key from a variable without using intermediate files. Note that inappropriate use of this syntax may have its security implications, such as writing secret key data to [error log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log).

> If [ssl_ntls](#ssl-ntls) is enabled, the directive can accept two arguments
> (the signature and the encryption parts of the key)
> instead of one:

> ```nginx
> listen ... ssl;

> ssl_ntls  on;

> # dual NTLS certificate
> ssl_certificate      sign.crt enc.crt;
> ssl_certificate_key  sign.key enc.key;

> # can be used together with a regular RSA certificate
> ssl_certificate  rsa.crt;
> ssl_certificate_key rsa.key;
> ```





### ssl_ciphers

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ciphers` ciphers;          |
|------------------------------------------------------------------------------------------|---------------------------------|
| Default                                                                                  | `ssl_ciphers HIGH:!aNULL:!MD5;` |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                    |

Specifies the enabled ciphers. The ciphers are specified in the format understood by the OpenSSL library, for example:

```nginx
ssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;
```

The list of ciphers depends on the version of OpenSSL installed.
The full list can be viewed using the `openssl ciphers` command.

#### WARNING
The `ssl_ciphers` directive does *not* configure ciphers for TLS
1.3 when using OpenSSL. To configure TLS 1.3 ciphers with OpenSSL, use the
[ssl_conf_command](#ssl-conf-command) directive, which was added to support advanced
SSL configuration.

- In LibreSSL, TLS 1.3 ciphers *can* be configured using
  `ssl_ciphers`.
- In BoringSSL, TLS 1.3 ciphers cannot be configured at all.





### ssl_client_certificate

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_client_certificate` file;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | —                                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                     |

Specifies a file with trusted CA certificates in the PEM format used to
[verify](#ssl-verify-client) client certificates and OCSP responses if
[ssl_stapling](#ssl-stapling) is enabled.

The list of certificates will be sent to clients. If this is not desired, the [ssl_trusted_certificate](#ssl-trusted-certificate) directive can be used.





### ssl_conf_command

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_conf_command` name value;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | —                                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                     |

Sets arbitrary OpenSSL [configuration commands](https://docs.openssl.org/master/man3/SSL_CONF_cmd/).

#### NOTE
The directive is supported when using OpenSSL 1.0.2 or higher.
To configure TLS 1.3 ciphers with OpenSSL, use the `Ciphersuites` command.

Several ssl_conf_command directives can be specified on the same level:

```nginx
ssl_conf_command Options PrioritizeChaCha;
ssl_conf_command Ciphersuites TLS_CHACHA20_POLY1305_SHA256;
```

These directives are inherited from the previous configuration level if and only if there are no ssl_conf_command directives defined on the current level.

#### WARNING
Note that configuring OpenSSL directly might result in unexpected behavior.





### ssl_crl

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_crl` file;   |
|------------------------------------------------------------------------------------------|-------------------|
| Default                                                                                  | —                 |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server      |

Specifies a file with revoked certificates (CRL) in the PEM format used to [verify](#ssl-verify-client) client certificates.





### ssl_dhparam

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_dhparam` file;   |
|------------------------------------------------------------------------------------------|-----------------------|
| Default                                                                                  | —                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server          |

Specifies a file with DH parameters for DHE ciphers.

#### WARNING
By default no parameters are set, and therefore DHE ciphers will not be used.





### ssl_early_data

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_early_data` `on` | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | `ssl_early_data off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                     |

Enables or disables TLS 1.3 [early data](https://datatracker.ietf.org/doc/html/rfc8446#section-2.3).

Requests sent within early data are subject to [replay attacks](https://datatracker.ietf.org/doc/html/rfc8470). To protect against such attacks at the application layer, the [$ssl_early_data](#v-ssl-early-data) variable should be used.

```nginx
proxy_set_header Early-Data $ssl_early_data;
```

#### NOTE
The directive is supported when using OpenSSL 1.1.1 or higher or [BoringSSL](https://boringssl.googlesource.com/boringssl/).





### ssl_ecdh_curve

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ecdh_curve` curve;   |
|------------------------------------------------------------------------------------------|---------------------------|
| Default                                                                                  | `ssl_ecdh_curve auto;`    |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server              |

Specifies a curve for ECDHE ciphers.

#### NOTE
When using OpenSSL 1.0.2 or higher, it is possible to specify multiple curves, for example:

```nginx
ssl_ecdh_curve prime256v1:secp384r1;
```

The special value `auto` corresponds to the list of curves built into the OpenSSL library for OpenSSL 1.0.2 or higher, or prime256v1 for older versions.

#### NOTE
When using OpenSSL 1.0.2 or higher, this directive sets the list of curves supported by the server. Thus, in order for ECDSA certificates to work, it is important to include the curves used in the certificates.





### ssl_encrypted_hello_key

#### Versionadded
Added in version 1.11.0.

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_encrypted_hello_key` file;   |
|------------------------------------------------------------------------------------------|-----------------------------------|
| Default                                                                                  | —                                 |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                      |

Specifies a file with an ECH private key and ECHConfigList in PEM format.
The directive can be specified multiple times.
Requires an OpenSSL or BoringSSL build with Encrypted Client Hello (ECH)
support; otherwise it is not supported.





### ssl_keylog_file

#### Versionadded
Added in version 1.12.0.

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_keylog_file` file;   |
|------------------------------------------------------------------------------------------|---------------------------|
| Default                                                                                  | —                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server              |

Specifies a file to log SSL/TLS keys for connections handled by the context,
using the [SSLKEYLOGFILE](https://www.ietf.org/archive/id/draft-thomson-tls-keylogfile-00.html)
format used by tools such as Wireshark to decrypt captured TLS traffic.

The directive should not be used with LibreSSL.

#### WARNING
The file contains sensitive TLS key material that can decrypt captured
traffic for the corresponding connections. Use this directive only for
debugging or protocol analysis, restrict access to the file, and remove it
when no longer needed.





### ssl_ntls

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ntls` `on` | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------|
| Default                                                                                  | `ssl_ntls off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server               |

Enables server-side support for NTLS when using the [TongSuo](https://github.com/Tongsuo-Project/Tongsuo) TLS library.

```nginx
listen ... ssl;
ssl_ntls  on;
```

#### NOTE
Angie must be built with the `--with-ntls` configuration parameter, with the corresponding SSL library with NTLS support

```default
./configure --with-openssl=../Tongsuo-8.3.0 \
            --with-openssl-opt=enable-ntls  \
            --with-ntls
```





### ssl_ocsp

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ocsp` `on` | `off` | `leaf`;   |
|------------------------------------------------------------------------------------------|-------------------------------------|
| Default                                                                                  | `ssl_ocsp off;`                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                        |

Enables OCSP validation of the client certificate chain. The `leaf` parameter enables validation of the client certificate only.

For the OCSP validation to work, the [ssl_verify_client](#ssl-verify-client) directive should be set to `on` or `optional`.

To resolve the OCSP responder hostname, the [resolver](https://en.angie.software//angie/docs/configuration/modules/http/index.md#resolver) directive should also be specified.

Example:

```nginx
ssl_verify_client on;
ssl_ocsp          on;
resolver          127.0.0.53;
```





### ssl_ocsp_cache

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ocsp_cache` `off` | [shared:name:size];   |
|------------------------------------------------------------------------------------------|------------------------------------------------|
| Default                                                                                  | `ssl_ocsp_cache off;`                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                                   |

Sets the name and size of the cache that stores client certificate status for OCSP validation. The cache is shared between all worker processes. A cache with the same name can be used in several virtual servers.

The `off` parameter prohibits the use of the cache.





### ssl_ocsp_responder

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ocsp_responder` uri;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| Default                                                                                  | —                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                |

Overrides the URI of the OCSP responder specified in the ["Authority Information Access"](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.2.1) certificate extension for [validation](#ssl-ocsp) of client certificates.

Only `http://` OCSP responders are supported:

```nginx
ssl_ocsp_responder http://ocsp.example.com/;
```





### ssl_password_file

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_password_file` file;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| Default                                                                                  | —                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                |

Specifies a file with passphrases for [secret keys](#ssl-certificate-key) where each passphrase is specified on a separate line. Passphrases are tried in turn when loading the key.

Example:

```nginx
http {
    ssl_password_file /etc/keys/global.pass;
    ...

    server {
        server_name www1.example.com;
        ssl_certificate_key /etc/keys/first.key;
    }

    server {
        server_name www2.example.com;

        # named pipe can also be used instead of a file
        ssl_password_file /etc/keys/fifo;
        ssl_certificate_key /etc/keys/second.key;
    }
}
```





### ssl_prefer_server_ciphers

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_prefer_server_ciphers` `on` | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| Default                                                                                  | `ssl_prefer_server_ciphers off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                                |

Specifies that server ciphers should be preferred over client ciphers when using the SSLv3 and TLS protocols.





### ssl_protocols

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_protocols` [`SSLv2`] [`SSLv3`] [`TLSv1`] [`TLSv1.1`] [`TLSv1.2`] [`TLSv1.3`];   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
| Default                                                                                  | `ssl_protocols TLSv1.2 TLSv1.3;`                                                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                                                                         |

Enables the specified protocols.

#### NOTE
The TLSv1.1 and TLSv1.2 parameters work only when OpenSSL 1.0.1 or higher is used.

The TLSv1.3 parameter works only when OpenSSL 1.1.1 or higher is used.





### ssl_reject_handshake

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_reject_handshake` `on` | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------------------|
| Default                                                                                  | `ssl_reject_handshake off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                           |

If enabled, SSL handshakes in the [server](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server) block will be rejected.

For example, in the following configuration, SSL handshakes with server names other than example.com are rejected:

```nginx
server {
    listen               443 ssl default_server;
    ssl_reject_handshake on;
}

server {
    listen              443 ssl;
    server_name         example.com;
    ssl_certificate     example.com.crt;
    ssl_certificate_key example.com.key;
}
```





### ssl_session_cache

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_session_cache` `off` | `none` | [builtin[:size]] [shared:name:size];   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| Default                                                                                  | `ssl_session_cache none;`                                                   |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                                                                |

Sets the types and sizes of caches that store session parameters. A cache can be of any of the following types:

| `off`     | the use of a session cache is strictly prohibited: Angie explicitly tells a client that sessions may not be reused.                                                                                                                                                                                                                                                                                                                                      |
|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `none`    | the use of a session cache is gently disallowed: Angie tells a client that sessions may be reused, but does not actually store session parameters in the cache.                                                                                                                                                                                                                                                                                          |
| `builtin` | a cache built in OpenSSL; used by one worker process only. The cache size is specified in sessions. If size is not given, it is equal to 20480 sessions. Use of the built-in cache can cause memory fragmentation.                                                                                                                                                                                                                                       |
| `shared`  | a cache shared between all worker processes. The cache size is specified in bytes; one megabyte can store about 4000 sessions. Each shared cache should have an arbitrary name. A cache with the same name can be used in several virtual servers. It is also used to automatically generate, store, and periodically rotate TLS session ticket keys unless configured explicitly using the [ssl_session_ticket_key](#ssl-session-ticket-key) directive. |

Both cache types can be used simultaneously, for example:

```nginx
ssl_session_cache builtin:1000 shared:SSL:10m;
```

but using only shared cache without the built-in cache should be more efficient.





### ssl_session_ticket_key

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_session_ticket_key` file;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | —                                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                     |

Sets a file with the secret key used to encrypt and decrypt TLS session tickets. The directive is necessary if the same key needs to be shared between multiple servers. By default, a randomly generated key is used.

If several keys are specified, only the first key is used to encrypt TLS session tickets. This allows configuring key rotation, for example:

```nginx
ssl_session_ticket_key current.key;
ssl_session_ticket_key previous.key;
```

The file must contain 80 or 48 bytes of random data and can be created using the following command:

```console
$ openssl rand 80 > ticket.key
```

Depending on the file size, either AES256 (for 80-byte keys) or AES128 (for 48-byte keys) will be used for encryption.





### ssl_session_tickets

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_session_tickets` `on` | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------------|
| Default                                                                                  | `ssl_session_tickets on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                          |

Enables or disables session resumption through [TLS session tickets](https://datatracker.ietf.org/doc/html/rfc5077).





### ssl_session_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_session_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `ssl_session_timeout 5m;`                                                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                                                                                                         |

Specifies a time during which a client may reuse the session parameters.





### ssl_stapling

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_stapling` `on` | `off`;   |
|------------------------------------------------------------------------------------------|--------------------------------|
| Default                                                                                  | `ssl_stapling off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                   |

Enables or disables [stapling of OCSP responses](https://datatracker.ietf.org/doc/html/rfc6066#section-8) by the server. Example:

```nginx
ssl_stapling on;
resolver 127.0.0.53;
```

For OCSP stapling to work, the certificate of the server certificate issuer should be known. If the [ssl_certificate](#ssl-certificate) file does not contain intermediate certificates, the certificate of the server certificate issuer should be present in the file specified by the [ssl_trusted_certificate](#ssl-trusted-certificate) directive.

#### WARNING
For a resolution of the OCSP responder hostname, the [resolver](https://en.angie.software//angie/docs/configuration/modules/http/index.md#resolver) directive should also be specified.





### ssl_stapling_file

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_stapling_file` file;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| Default                                                                                  | —                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                |

When set, the stapled OCSP response will be taken from the specified file instead of querying the OCSP responder specified in the server certificate.

The file should be in the DER format as produced by the `openssl ocsp` command.





### ssl_stapling_responder

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_stapling_responder` `uri`;   |
|------------------------------------------------------------------------------------------|-----------------------------------|
| Default                                                                                  | —                                 |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                      |

Overrides the URI of the OCSP responder specified in the ["Authority Information Access"](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.2.1) certificate extension.

Only `http://` OCSP responders are supported:

```nginx
ssl_stapling_responder http://ocsp.example.com/;
```





### ssl_stapling_verify

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_stapling_verify` `on` | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------------|
| Default                                                                                  | `ssl_stapling_verify off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                          |

Enables or disables verification of OCSP responses by the server.

For verification to work, the certificate of the server certificate issuer, the root certificate, and all intermediate certificates should be configured as trusted using the [ssl_trusted_certificate](#ssl-trusted-certificate) directive.





### ssl_trusted_certificate

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_trusted_certificate` file;   |
|------------------------------------------------------------------------------------------|-----------------------------------|
| Default                                                                                  | —                                 |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                      |

Specifies a file with trusted CA certificates in the PEM format used to [verify](#ssl-verify-client) client certificates and OCSP responses if [ssl_stapling](#ssl-stapling) is enabled.

In contrast to the certificate set by [ssl_client_certificate](#ssl-client-certificate), the list of these certificates will not be sent to clients.





### ssl_verify_client

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_verify_client` `on` | `off` | `optional` | `optional_no_ca`;   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
| Default                                                                                  | `ssl_verify_client off;`                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                                                        |

Enables verification of client certificates. The verification result is stored in the [$ssl_client_verify](#v-ssl-client-verify) variable.

| `optional`       | requests the client certificate and verifies it if the certificate is present.                                                                                                                                             |
|------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `optional_no_ca` | requests the client certificate but does not require it to be signed by a trusted CA certificate. This is intended for use in cases when a service that is external to Angie performs the actual certificate verification. |





### ssl_verify_depth

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_verify_depth` number;   |
|------------------------------------------------------------------------------------------|------------------------------|
| Default                                                                                  | `ssl_verify_depth 1;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                 |

Sets the verification depth in the client certificates chain.



## Error Processing

The `http_ssl` module supports several non-standard error codes that can be used for redirects using the [error_page](https://en.angie.software//angie/docs/configuration/modules/http/index.md#error-page) directive:

| `495`   | an error has occurred during the client certificate verification;   |
|---------|---------------------------------------------------------------------|
| `496`   | a client has not presented the required certificate;                |
| `497`   | a regular request has been sent to the HTTPS port.                  |

The redirection happens after the request is fully parsed and the variables, such as [$request_uri](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-request-uri), [$uri](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-uri), [$args](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-args) and others, are available.



## Built-in Variables

The http_ssl module supports built-in variables:



### `$ssl_alpn_protocol`

returns the protocol selected by ALPN during the SSL handshake, or an empty string otherwise.



### `$ssl_cipher`

returns the name of the cipher used for an established SSL connection.



### `$ssl_ciphers`

returns the list of ciphers supported by the client. Known ciphers are listed by names, unknown are shown in hexadecimal, for example:

> AES128-SHA:AES256-SHA:0x00ff

#### NOTE
The variable is fully supported only when using OpenSSL version 1.0.2 or higher. With older versions, the variable is available only for new sessions and lists only known ciphers.



### `$ssl_client_escaped_cert`

returns the client certificate in the PEM format (urlencoded) for an established SSL connection.



### `$ssl_client_fingerprint`

returns the SHA1 fingerprint of the client certificate for an established SSL connection.



### `$ssl_client_i_dn`

returns the "issuer DN" string of the client certificate for an established SSL connection according to [RFC 2253](https://datatracker.ietf.org/doc/html/rfc2253).



### `$ssl_client_i_dn_legacy`

returns the "issuer DN" string of the client certificate for an established SSL connection.



### `$ssl_client_raw_cert`

returns the client certificate in the PEM format for an established SSL connection.



### `$ssl_client_s_dn`

returns the "subject DN" string of the client certificate for an established SSL connection according to [RFC 2253](https://datatracker.ietf.org/doc/html/rfc2253).



### `$ssl_client_s_dn_legacy`

returns the "subject DN" string of the client certificate for an established SSL connection.



### `$ssl_client_serial`

returns the serial number of the client certificate for an established SSL connection.



### `$ssl_client_sigalg`

returns the [signature algorithm](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-16) for the client certificate for an established SSL connection.

#### NOTE
The variable is supported only when using OpenSSL version 3.5 or higher. With older versions, the variable value will be an empty string.

#### NOTE
The variable is available only for new sessions.



### `$ssl_client_v_end`

returns the end date of the client certificate.



### `$ssl_client_v_remain`

returns the number of days until the client certificate expires.



### `$ssl_client_v_start`

returns the start date of the client certificate.



### `$ssl_client_verify`

returns the result of client certificate verification: `SUCCESS`, `FAILED:reason`, and `NONE` if a certificate was not present.



### `$ssl_curve`

returns the negotiated curve used for key exchange during the SSL handshake. Known curves are listed by names, unknown are shown in hexadecimal, for example:

> prime256v1

#### NOTE
The variable is supported only when using OpenSSL version 3.0 or higher. With older versions, the variable value will be an empty string.



### `$ssl_curves`

returns the list of curves supported by the client. Known curves are listed by names, unknown are shown in hexadecimal, for example:

> 0x001d:prime256v1:secp521r1:secp384r1

#### NOTE
The variable is supported only when using OpenSSL version 1.0.2 or higher. With older versions, the variable value will be an empty string.

The variable is available only for new sessions.



### `$ssl_early_data`

returns "1" if TLS 1.3 [early data](#ssl-early-data) is used and the handshake is not complete, otherwise "".



### `$ssl_encrypted_hello`

#### Versionadded
Added in version 1.11.0.

returns "1" if Encrypted Client Hello (ECH) is used, otherwise "".



### `$ssl_protocol`

returns the protocol of an established SSL connection.



### `$ssl_server_cert_type`

takes the values `RSA`, `DSA`, `ECDSA`, `ED448`,
`ED25519`, `SM2`, `RSA-PSS`, or `unknown` depending
on the type of server certificate and key.



### `$ssl_server_name`

returns the server name requested through [SNI](http://en.wikipedia.org/wiki/Server_Name_Indication).



### `$ssl_session_id`

returns the session identifier of an established SSL connection.



### `$ssl_session_reused`

returns "r" if an SSL session was reused, or "." otherwise.



### `$ssl_sigalg`

returns the [signature algorithm](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-16) for the server certificate for an established SSL connection.

#### NOTE
The variable is supported only when using OpenSSL version 3.5 or higher. With older versions, the variable value will be an empty string.

#### NOTE
The variable is available only for new sessions.



### `$ssl_sigalgs`

returns the list of [signature algorithms](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-16) offered by the client during the SSL handshake, as a colon-separated list.

#### NOTE
With OpenSSL version 4.0 or higher, algorithms are returned by name; an
algorithm without a name falls back to its raw hexadecimal code. SSL
libraries that expose the older signature-algorithm API return all
algorithms as raw hexadecimal codes. Builds without a supported
signature-algorithm API return an empty value.


# https://en.angie.software/angie/docs/configuration/modules/http/http_stub_status.md





# Stub Status

The module provides access to basic server status information.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module isn't built
by default; it must be enabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--with-http_stub_status_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
location = /basic_status {
    stub_status;
}
```

This configuration creates a simple web page with basic status information which may look as follows:

```console
Active connections: 291
server accepts handled requests
 16630948 16630948 31070465
Reading: 6 Writing: 179 Waiting: 106
```



## Directives





### stub_status

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `stub_status`;   |
|------------------------------------------------------------------------------------------|------------------|
| Default                                                                                  | —                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | server, location |

The status information will be accessible from the surrounding location.



## Data

The following status information is provided:



### `Active connections`

The current number of active client connections including Waiting connections.



### `accepts`

The total number of accepted client connections.



### `handled`

The total number of handled connections. Generally, the parameter value is the same as accepts unless some resource limits have been reached (for example, the [worker_connections](https://en.angie.software//angie/docs/configuration/modules/core.md#worker-connections) limit).



### `requests`

The total number of client requests.



### `Reading`

The current number of connections where Angie is reading the request header.



### `Writing`

The current number of connections where Angie is writing the response back to the client.



### `Waiting`

The current number of idle client connections waiting for a request.



## Built-in Variables



### `$connections_active`

Same as the Active connections value.



### `$connections_reading`

Same as the Reading value.



### `$connections_waiting`

Same as the Waiting value.



### `$connections_writing`

Same as the Writing value.


# https://en.angie.software/angie/docs/configuration/modules/http/http_sub.md





# Sub

The module is a filter that modifies a response by replacing one specified string with another.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module isn't built
by default; it must be enabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--with-http_sub_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
location / {
    sub_filter '

## Directives





### sub_filter

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `sub_filter` string replacement;   |
|------------------------------------------------------------------------------------------|------------------------------------|
| Default                                                                                  | —                                  |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location             |

Sets a string to replace and a replacement string. The string to replace is matched ignoring the case. The string to replace and replacement string can contain [variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables). Several `sub_filter` directives can be specified on the same configuration level. These directives are inherited from the previous configuration level if and only if there are no `sub_filter` directives defined on the current level.





### sub_filter_last_modified

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `sub_filter_last_modified` `on` | `off`;   |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| Default                                                                                  | `sub_filter_last_modified off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                     |

Allows preserving the `Last-Modified` header field from the original response during replacement to facilitate response caching.

By default, the header field is removed as contents of the response are modified during processing.





### sub_filter_once

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `sub_filter_once` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-----------------------------------|
| Default                                                                                  | `sub_filter_once on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location            |

Indicates whether to look for each string to replace once or repeatedly.





### sub_filter_types

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `sub_filter_types` mime-type ...;   |
|------------------------------------------------------------------------------------------|-------------------------------------|
| Default                                                                                  | `sub_filter_types text/html;`       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location              |

Enables string replacement in responses with the specified MIME types in addition to `text/html`. The special value "\*" matches any MIME type.


# https://en.angie.software/angie/docs/configuration/modules/http/http_tunnel.md





# Tunnel

#### Versionadded
Added in version 1.12.0.

The Tunnel module (`ngx_http_tunnel_module`) handles HTTP/1.1
[CONNECT](https://datatracker.ietf.org/doc/html/rfc9110#section-9.3.6)
requests and establishes an end-to-end virtual connection between the client
and a backend server, allowing Angie to act as a forwarding proxy.

Access to the tunnel is controlled with the standard access directives:
[auth_basic](https://en.angie.software//angie/docs/configuration/modules/http/http_auth_basic.md#id1), [satisfy](https://en.angie.software//angie/docs/configuration/modules/http/index.md#satisfy), and [auth_delay](https://en.angie.software//angie/docs/configuration/modules/http/index.md#auth-delay).



## Configuration Example

```nginx
http {

    map $host $allow_host {
        hostnames;

        example.org    1;
        *.example.org  1;
    }

    server {
        listen 8000;

        resolver 127.0.0.53;

        if ($allow_host != 1) {
            return 502;
        }

        tunnel_pass;
    }
}
```



## Directives





### tunnel_bind

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `tunnel_bind` address [`transparent`] | `off`;   |
|------------------------------------------------------------------------------------------|--------------------------------------------------|
| Default                                                                                  | —                                                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                           |

Makes outgoing connections to a backend server originate from the specified
local IP address with an optional port. The parameter value can contain
variables. The special value `off` cancels the effect of the
`tunnel_bind` directive inherited from the previous configuration level,
which allows the system to auto-assign the local IP address and port.

The `transparent` parameter allows outgoing connections to a backend
server to originate from a non-local IP address, for example, from a real IP
address of a client:

```nginx
tunnel_bind $remote_addr transparent;
```

In order for this parameter to work, it is usually necessary to run Angie
worker processes with the [superuser](https://en.angie.software//angie/docs/configuration/modules/core.md#user) privileges. On Linux it is
not required as if the `transparent` parameter is specified, worker
processes inherit the `CAP_NET_RAW` capability from the master process.





### tunnel_buffer_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `tunnel_buffer_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `tunnel_buffer_size 4k|8k;`                                                                                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                              |

Sets the size of the buffer used for reading data from the backend server.
It also sets the size of the buffer used for reading data from the client.
By default, the buffer size is equal to one memory page. This is either 4K or
8K, depending on a platform.





### tunnel_connect_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `tunnel_connect_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `tunnel_connect_timeout 60s;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                  |

Defines a timeout for establishing a connection with a backend server. It
should be noted that this timeout cannot usually exceed 75 seconds.





### tunnel_next_upstream

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `tunnel_next_upstream` `error` | `timeout` | `off` ...;   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------|
| Default                                                                                  | `tunnel_next_upstream error timeout;`                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                    |

Specifies in which cases a request should be passed to the next server:

| `error`   | an error occurred while establishing a connection with the server or
reading data from it;                                |
|-----------|-------------------------------------------------------------------------------------------------------------------------------|
| `timeout` | a timeout has occurred while establishing a connection with the server,
passing a request to it, or reading data from it; |
| `off`     | disables passing a request to the next server.                                                                                |

Passing a request to the next server is only possible if nothing has been sent
to a client yet. If an error or timeout occurs in the middle of
transferring a response, fixing it is impossible.

The directive also defines what is considered an
[unsuccessful attempt](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) of communication with a server. The
cases of `error` and `timeout` are always considered unsuccessful
attempts, even if they are not specified in the directive.

Passing a request to the next server can be limited by
[the number of tries](#tunnel-next-upstream-tries) and by
[time](#tunnel-next-upstream-timeout).





### tunnel_next_upstream_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `tunnel_next_upstream_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `tunnel_next_upstream_timeout 0;`                                                                                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                        |

Limits the time during which a request can be passed to the
[next server](#tunnel-next-upstream). The `0` value turns off this
limitation.





### tunnel_next_upstream_tries

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `tunnel_next_upstream_tries` number;   |
|------------------------------------------------------------------------------------------|----------------------------------------|
| Default                                                                                  | `tunnel_next_upstream_tries 0;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                 |

Limits the number of possible tries for passing a request to the
[next server](#tunnel-next-upstream). The `0` value turns off this
limitation.





### tunnel_pass

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `tunnel_pass` [address];         |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | —                                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | server, location, if in location |

Enables handling of CONNECT requests and sets the address of a backend server.
By default, the address is `$host:$request_port` and is taken from the
client request. In most cases, `tunnel_pass` does not require configuring
any arguments.

The address can be specified as a domain name or IP address, and a port:

```nginx
tunnel_pass localhost:9000;
```

or as a UNIX-domain socket path:

```nginx
tunnel_pass unix:/tmp/backend.socket;
```

If a domain name resolves to several addresses, all of them will be used in a
[round-robin](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#round-robin) fashion. In addition, an address can be specified as a
[server group](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream).

The parameter value can contain variables. In this case, if an address is
specified as a domain name, the name is searched among the described
[server groups](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream), and, if not found, is determined using a
[resolver](https://en.angie.software//angie/docs/configuration/modules/http/index.md#resolver).





### tunnel_read_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `tunnel_read_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `tunnel_read_timeout 60s;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                               |

Sets the timeout between two successive read or write operations on client or
backend server connections. If no data is transmitted within this time, the
connection is closed.





### tunnel_send_lowat

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `tunnel_send_lowat` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `tunnel_send_lowat 0;`                                                                                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                             |

If the directive is set to a non-zero value, Angie will try to minimize the
number of send operations on outgoing connections to a backend server by using
either the `NOTE_LOWAT` flag of the `kqueue` method, or the
`SO_SNDLOWAT` socket option, with the specified size.

This directive is ignored on Linux, Solaris, and Windows.





### tunnel_send_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `tunnel_send_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `tunnel_send_timeout 60s;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                               |

Sets a timeout for transmitting data to the backend server. The timeout is
set only between two successive write operations, not for the whole
transmission. If the backend server does not receive anything within this
time, the connection is closed.





### tunnel_socket_keepalive

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `tunnel_socket_keepalive` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-------------------------------------------|
| Default                                                                                  | `tunnel_socket_keepalive off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                    |

Configures the "TCP keepalive" behavior for outgoing connections to a backend
server. By default, the operating system's settings are in effect for the
socket. If the directive is set to the value `on`, the
`SO_KEEPALIVE` socket option is turned on for the socket.


# https://en.angie.software/angie/docs/configuration/modules/http/http_upstream.md










# Upstream

Provides a context for describing groups of servers that can be used in the [proxy_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass), [fastcgi_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-pass), [uwsgi_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-pass), [scgi_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-pass), [memcached_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_memcached.md#memcached-pass), and [grpc_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-pass) directives.



## Configuration Example

```nginx
upstream backend {
    zone backend 1m;
    server backend1.example.com       weight=5;
    server backend2.example.com:8080;
    server backend3.example.com       service=_example._tcp resolve;
    server unix:/tmp/backend3;

    server backup1.example.com:8080   backup;
    server backup2.example.com:8080   backup;
}

resolver 127.0.0.53 status_zone=resolver;

server {
    location / {
        proxy_pass http://backend;
    }
}
```



## Directives





### backup_switch (PRO)

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `backup_switch` `permanent`[=time];   |
|------------------------------------------------------------------------------------------|---------------------------------------|
| Default                                                                                  | —                                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                              |

The directive enables the ability to start server selection not from the primary group,
but from the *active* group, i.e., the one where a server was successfully found last time.
If a server cannot be found in the active group for the next request,
and the search moves to the backup group,
then this group becomes active,
and subsequent requests are first directed to servers in this group.

If the `permanent` parameter is defined without a [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units) value,
the group remains active after selection,
and automatic rechecking of groups with lower levels does not occur.
If time is specified,
the active status of the group expires after the specified interval,
and the balancer again checks groups with lower levels,
returning to them if the servers are working normally.

Example:

```nginx
upstream my_backend {
    zone my_backend 1m;
    server primary1.example.com;
    server primary2.example.com;

    server backup1.example.com backup;
    server backup2.example.com backup;

    backup_switch permanent=2m;
}
```

If the balancer switches from primary servers to the backup group,
all subsequent requests are handled by this backup group for 2 minutes.
After 2 minutes elapse, the balancer rechecks the primary servers
and makes them active again if they are working normally.





### bind_conn (PRO)

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `bind_conn` value;   |
|------------------------------------------------------------------------------------------|----------------------|
| Default                                                                                  | —                    |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream             |

Allows binding a server connection to a client connection when the
value, specified as a string of variables, becomes different from `""` and
`"0"`.

If the bound server cannot take the next request over the client connection —
for example after [resolve](#reresolve) removes its address from the group,
or while the server is unavailable — the bound connection is closed and another
server is chosen via the configured balancing method.

#### WARNING
The `bind_conn` directive must be used after all directives
that set a load balancing method,
otherwise it will not work.
If it is used together with the [sticky](#u-sticky) directive,
then `bind_conn` must come after `sticky`.

#### WARNING
When using the directive, the [Proxy](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy) module settings
must allow the use of persistent connections, for example:

```nginx
proxy_http_version 1.1;
proxy_set_header Connection "";
```

A typical use case for the directive is proxying connections with
NTLM authentication, where it is necessary to ensure client-to-server binding at
the beginning of negotiation:

```nginx
map $http_authorization $ntlm {
    ~*^NTLM       1;
    ~*^Negotiate  1;
}

upstream ntlm_backend {
    zone ntlm_backend 1m;
    server 127.0.0.1:8080;
    bind_conn $ntlm;
}

server {
    # ...
    location / {
        proxy_pass http://ntlm_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        # ...
    }
}
```





### feedback (PRO)

#### Versionchanged
Changed in version 1.12.0: PRO

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `feedback` variable [`inverse`] [`factor=`number] [`account=`condition_variable] [`last_byte`];   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------|
| Default                                                                                  | —                                                                                                 |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                                                                                          |

Sets up a feedback-based load balancing mechanism in the `upstream`.
It dynamically adjusts balancing decisions
by multiplying the weight of each proxied server by the average feedback value,
which changes over time depending on the value of the variable
and is subject to an optional condition.

The following parameters can be specified:

| `variable`   | The variable from which the feedback value is taken.
It should represent a performance or health metric;
it is assumed that the server provides it in headers or otherwise.

The value is evaluated with each response from the server
and is factored into the moving average
according to the `inverse` and `factor` settings.                                                                                                                                                                                                                                                                                                                                                                                       |
|--------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `inverse`    | If the parameter is set, the feedback value is interpreted inversely:
lower values indicate better performance.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `factor`     | The factor by which the feedback value is considered
when calculating the average.
Valid values are integers from 0 to 99.
Default is `90`.

The average is calculated using the [exponential smoothing](https://en.wikipedia.org/wiki/Exponential_smoothing) formula.

The larger the factor, the less new values affect the average;
if `90` is specified, then 90% of the previous value
and only 10% of the new value will be taken.                                                                                                                                                                                                                                                                   |
| `account`    | Specifies a condition variable
that controls which responses are considered in the calculation.
The average value is updated with the feedback value from the response
only if the condition variable of that response
is not equal to `""` or `"0"`.

#### NOTE
By default, responses during [active checks](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe)
are not included in the calculation;
combining the [$upstream_probe](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#v-upstream-probe) variable
with `account` allows including these responses
or even excluding everything else. |
| `last_byte`  | Allows processing data from the proxied server after receiving
the complete response, not just the header.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

Example:

```nginx
upstream backend {

    zone backend 1m;

    feedback $feedback_value factor=80 account=$condition_value;

    server backend1.example.com;
    server backend2.example.com;
}

map $upstream_http_custom_score $feedback_value {
    "high"                      100;
    "medium"                    75;
    "low"                       50;
    default                     10;
}

map $upstream_probe $condition_value {
    "high_priority" "1";
    "low_priority"  "0";
    default         "1";
}
```

This configuration categorizes server responses by feedback levels
based on specific scores from response header fields,
and also adds a condition on [$upstream_probe](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#v-upstream-probe)
to consider only responses from the `high_priority` active check
or responses to regular client requests.





### hash

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `hash` key [`consistent`];   |
|------------------------------------------------------------------------------------------|------------------------------|
| Default                                                                                  | —                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                     |

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), support for this
directive can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-http_upstream_hash_module`.

Specifies a load balancing method for a server group where the client-server mapping is determined using the hashed key value. The key can contain [variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables). Note that adding or removing a server from the group may result in remapping most of the keys to different servers. The method is compatible with the [Cache::Memcached](https://metacpan.org/pod/Cache::Memcached) Perl library.

```nginx
hash $remote_addr;
```

When using domain names that resolve to multiple IP addresses
(for example, with the `resolve` parameter),
the server does not sort the received addresses, so their order may differ
across different servers, which affects client distribution.
To ensure consistent distribution,
use the `consistent` parameter.

If the `consistent` parameter is specified, the [ketama](https://www.metabrew.com/article/libketama-consistent-hashing-algo-memcached-clients) consistent hashing method will be used instead. The method ensures that only a few keys will be remapped to different servers when a server is added to or removed from the group. This helps to achieve a higher cache hit ratio for caching servers. The method is compatible with the [Cache::Memcached::Fast](https://metacpan.org/pod/Cache::Memcached::Fast) Perl library with the `ketama_points` parameter set to 160.





### ip_hash

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ip_hash`;   |
|------------------------------------------------------------------------------------------|--------------|
| Default                                                                                  | —            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream     |

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), support for this
directive can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-http_upstream_ip_hash_module`.

Specifies a load balancing method for the group where requests are distributed among servers based on client IP addresses. The first three octets of the client's IPv4 address or the entire IPv6 address are used as a hashing key. The method ensures that requests from the same client will always be passed to the same server except when this server is unavailable. In that case, client requests will be passed to another server. Most likely this will also be the same server.

If one of the servers needs to be temporarily removed, it should be marked with the `down` parameter to preserve the current hashing of client IP addresses:

```nginx
upstream backend {
    zone backend 1m;
    ip_hash;

    server backend1.example.com;
    server backend2.example.com;
    server backend3.example.com down;
    server backend4.example.com;
}
```





### keepalive

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `keepalive` connections;   |
|------------------------------------------------------------------------------------------|----------------------------|
| Default                                                                                  | —                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                   |

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), support for this
directive can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-http_upstream_keepalive_module`.

Activates the cache of connections to upstream servers.

The `connections` parameter sets the maximum number of idle keepalive connections to upstream servers that are preserved in the cache of each worker process. When this number is exceeded, the least recently used connections are closed.

#### NOTE
It should be particularly noted that the `keepalive` directive does not limit the total number of connections to upstream servers that Angie worker processes can open. The `connections` parameter should be set low enough to let upstream servers process new incoming connections as well.

#### NOTE
Cached connections are matched to upstream servers by address. When
[resolve](#reresolve) or the [API command](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-config-methods)
`DELETE` removes an address from the group, connections cached for
that address are not closed: they occupy cache slots until the server
closes them, [keepalive_timeout](#u-keepalive-timeout) expires, or they are evicted, and
are reused only if that address returns to the group. The
[proxy_connection_drop](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-connection-drop), [fastcgi_connection_drop](https://en.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-connection-drop),
[uwsgi_connection_drop](https://en.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-connection-drop), [scgi_connection_drop](https://en.angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-connection-drop), and
[grpc_connection_drop](https://en.angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-connection-drop) directives do not close them: they act only on
active connections.

#### WARNING
The `keepalive` directive must be used after all directives that set
a load balancing method, otherwise it will not work.

Example configuration of memcached upstream with keepalive connections:

```nginx
upstream memcached_backend {
    zone memcached_backend 1m;
    server 127.0.0.1:11211;
    server 10.0.0.2:11211;

    keepalive 32;
}

server {
    #...

    location /memcached/ {
        set $memcached_key $uri;
        memcached_pass memcached_backend;
    }

}
```

For HTTP, the [proxy_http_version](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http-version) directive should be set to "1.1" and the `Connection` header field should be cleared:

```nginx
upstream http_backend {
    zone http_backend 1m;
    server 127.0.0.1:8080;

    keepalive 16;
}

server {
    #...

    location /http/ {
        proxy_pass http://http_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
    #    ...
    }
}
```

#### NOTE
Alternatively, HTTP/1.0 persistent connections can be used by passing the "Connection: Keep-Alive" header field to an upstream server, though this method is not recommended.

For FastCGI servers, it is required to set [fastcgi_keep_conn](https://en.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-keep-conn) for keepalive connections to work:

```nginx
upstream fastcgi_backend {
    zone fastcgi_backend 1m;
    server 127.0.0.1:9000;

    keepalive 8;
}

server {
    #...

    location /fastcgi/ {
        fastcgi_pass fastcgi_backend;
        fastcgi_keep_conn on;
    #    ...
    }
}
```

#### NOTE
SCGI and uwsgi protocols do not have a concept of keepalive connections.





### keepalive_requests

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `keepalive_requests` number;   |
|------------------------------------------------------------------------------------------|--------------------------------|
| Default                                                                                  | `keepalive_requests 1000;`     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                       |

Sets the maximum number of requests that can be served through one keepalive connection. After the maximum number of requests is made, the connection is closed.

Closing connections periodically is necessary to free per-connection memory allocations. Therefore, using too high maximum number of requests could result in excessive memory usage and not recommended.





### keepalive_time

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `keepalive_time` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `keepalive_time 1h;`                                                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                                                                                                        |

Limits the maximum time during which requests can be processed through one keepalive connection. After this time is reached, the connection is closed following the subsequent request processing.





### keepalive_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `keepalive_timeout` timeout;   |
|------------------------------------------------------------------------------------------|--------------------------------|
| Default                                                                                  | `keepalive_timeout 60s;`       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                       |

Sets a timeout during which an idle keepalive connection to an upstream server will stay open.

#### NOTE
This timeout governs idle connections to upstream servers. It is not
the client-side [keepalive_timeout](https://en.angie.software//angie/docs/configuration/modules/http/index.md#keepalive-timeout) (in the http, server, or
location context), and it does not affect how long Angie waits for a new
upstream connection to be established, which is set by the protocol's own
connect timeout, such as [proxy_connect_timeout](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-connect-timeout).





### least_conn

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `least_conn`;   |
|------------------------------------------------------------------------------------------|-----------------|
| Default                                                                                  | —               |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream        |

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), support for this
directive can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-http_upstream_least_conn_module`.

Specifies that a group should use a load balancing method where a request is passed to the server with the least number of active connections, taking into account weights of servers. If there are several such servers, they are tried in turn using a weighted round-robin balancing method.





### least_time

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `least_time` `header` | `last_byte` [`factor=`number] [`account=`condition_variable];   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
| Default                                                                                  | —                                                                                       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                                                                                |

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), support for this
directive can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-http_upstream_least_time_module`.

Specifies that the group should use a load balancing method where an active
server's chance of receiving the request is inversely proportional to its
average response time; the less it is, the more requests a server gets.

| `header`    | The directive accounts for the average time to receive response headers.   |
|-------------|----------------------------------------------------------------------------|
| `last_byte` | The directive uses the average time to receive the entire response.        |

| `factor`   | Serves the same purpose as [response_time_factor](#u-response-time-factor)
and overrides it if the parameter is set.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `account`  | Specifies a condition variable
that controls which responses are included in the calculation.
The average is updated
only if the condition variable for the response
is not `""` or `"0"`.

#### NOTE
By default, [probes (PRO)](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe)
are not included in the calculation;
combining the [$upstream_probe](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#v-upstream-probe) variable
with `account` allows including these responses
or even excluding everything else. |

Current values are presented as `header_time` (headers only)
and `response_time` (entire responses) in the server's `health` object
among the [upstream metrics](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-upstreams) in the API.





### queue (PRO)

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `queue` number [`timeout=`time];   |
|------------------------------------------------------------------------------------------|------------------------------------|
| Default                                                                                  | —                                  |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                           |

If it is not possible to assign a proxied server to a request on the first attempt
(for example, during a brief service interruption
or when there is a surge in load reaching the [max_conns](#u-server) limit),
the request is not rejected;
instead, Angie attempts to enqueue it for processing.

The number parameter of the directive sets the maximum number of requests
in the queue for a [worker process](https://en.angie.software//angie/docs/configuration/modules/core.md#worker-processes).
If the queue is full,
a `502 (Bad Gateway)` error is returned to the client.

#### NOTE
The logic of the [proxy_next_upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-next-upstream) directive also applies to queued requests.
Specifically, if a server was selected for a request
but it cannot be handed over to it,
the request may be returned to the queue.

If a server is not selected to process a queued request
within the [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units) set by `timeout`
(default is 60 seconds),
a `502 (Bad Gateway)` error is returned to the client.
Requests from clients that prematurely close the connection are also removed from the queue;
there are counters for the states of requests passing through the queue in the [API](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#a-queue).

#### WARNING
The `queue` directive must be used after all directives that set the
load balancing method; otherwise, it won't work.





### random

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `random` [`two`];   |
|------------------------------------------------------------------------------------------|---------------------|
| Default                                                                                  | —                   |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream            |

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), support for this
directive can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-http_upstream_random_module`.

Specifies a load balancing method for the group where a request is passed to a randomly selected server, taking into account server weights.

If the optional `two` parameter is specified, Angie randomly selects two servers, then selects one of them using the [least_conn](#u-least-conn) method, where a request is passed to the server with the least number of active connections.





### response_time_factor

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `response_time_factor` number;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | `response_time_factor 90;`       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                         |

Sets the smoothing factor for the **previous** value when calculating the average
response time for the [least_time](#u-least-time) load balancing method using the
[exponentially weighted moving average](https://en.wikipedia.org/wiki/Moving_average#Exponential_moving_average) formula.

The higher the specified number, the less new values affect the average; if
`90` is specified, 90% of the previous value and only 10% of
the new value are taken. Valid values range from 0 to 99 inclusive.

Current calculation results are presented as `header_time`
(headers only) and `response_time` (entire responses) in the server's `health`
object among the [upstream metrics](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-upstreams) in the API.

#### NOTE
Only successful responses are included in the calculation; what is considered an unsuccessful
response is determined by the [proxy_next_upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-next-upstream),
[fastcgi_next_upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-next-upstream), [uwsgi_next_upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-next-upstream),
[scgi_next_upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-next-upstream), [memcached_next_upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_memcached.md#memcached-next-upstream), and
[grpc_next_upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-next-upstream) directives. Additionally, the `header_time`
value is recalculated only if all headers are received and processed, and
`response_time` — only if the entire response is received.





### server

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `server` address [parameters];   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | —                                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                         |

Defines the address and other parameters of a server. The address can be specified as a domain name or IP address, with an optional port, or as a UNIX-domain socket path specified after the `unix:` prefix. If a port is not specified, port 80 is used. A domain name that resolves to multiple IP addresses defines multiple servers at once.

The following parameters can be defined:

| `weight=`number    | Sets the weight of the server. Default is 1.                                                                                                                                                                                                         |
|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `max_conns=`number | Limits the maximum number of simultaneous active connections to the proxied server. The default value is `0`, meaning there is no limit. If the group does not reside in the [shared memory zone](#u-zone), the limitation works per worker process. |

#### NOTE
With [idle keepalive connections](#u-keepalive) enabled, multiple [worker processes](https://en.angie.software//angie/docs/configuration/modules/core.md#worker-processes), and a [shared memory zone](#u-zone), the total number of active and idle connections to the proxied server may exceed the `max_conns` value.



`max_fails=`number — sets the number of unsuccessful attempts to communicate with the server
that should occur during the specified [fail_timeout](#fail-timeout)
period for the server to be considered unavailable;
after this, it will be checked again after the same period.

What is considered an unsuccessful attempt
is defined by the [proxy_next_upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-next-upstream),
[fastcgi_next_upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-next-upstream), [uwsgi_next_upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-next-upstream),
[scgi_next_upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-next-upstream), [memcached_next_upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_memcached.md#memcached-next-upstream), and
[grpc_next_upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-next-upstream) directives.

When `max_fails` is exceeded, the server is also considered unavailable from the perspective of
[upstream_probe (PRO)](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe); client requests will not be directed to it
until checks determine it is available.

#### NOTE
If a `server` directive in a group resolves to multiple servers,
its `max_fails` setting applies to each server separately.

If after resolving all `server` directives
only one server remains in the upstream,
the `max_fails` setting has no effect and will be ignored.

| `max_fails=1`   | Default number of attempts;   |
|-----------------|-------------------------------|
| `max_fails=0`   | Disables attempt accounting.  |



`fail_timeout=`time — sets the period of time during which
a specified number of unsuccessful attempts to communicate with the server
([max_fails](#max-fails)) must occur for the server to be considered unavailable.
The server then remains unavailable for the same period of time
before being checked again.

Default value is 10 seconds.

#### NOTE
If a `server` directive in a group resolves to multiple servers,
its `fail_timeout` setting applies to each server separately.

If after resolving all `server` directives
only one server remains in the upstream,
the `fail_timeout` setting has no effect and will be ignored.

| `backup`   | Marks the server as a backup server. It will be passed requests when the primary servers are unavailable.

If the [backup_switch (PRO)](#u-backup-switch) directive is specified,
its active backup logic also applies.   |
|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `down`     | Marks the server as permanently unavailable.                                                                                                                                                                                          |
| `drain`    | Marks the server as draining; this means
it only receives requests from sessions
previously bound via [sticky](#u-sticky).
Otherwise, the behavior is the same as in `down` mode.                                         |

#### WARNING
The `backup` parameter cannot be used together with the
[hash](#u-hash), [ip_hash](#u-ip-hash), and
[random](#u-random) load balancing methods.

The `down` and `drain` parameters are mutually exclusive.



| `resolve`      | Allows monitoring changes to the list of IP addresses corresponding to
a domain name and updating it without reloading the configuration.
The group must reside in
[shared memory](#u-zone);
a [resolver](https://en.angie.software//angie/docs/configuration/modules/http/index.md#resolver) must also be defined.
Connections [cached](#u-keepalive) for an address are not closed
when that address is removed from the group.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
|----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `service=`name | Enables resolution of DNS SRV records and sets the service name. For
the parameter to work, the `resolve` parameter must be specified for the server,
without specifying a port in the hostname.

If the service name does not contain a dot, a name is formed according to the RFC standard:
the service name is prefixed with `_`,
then `_tcp` is appended after a dot.
Thus, the service name `http` results in `_http._tcp`.

Angie resolves SRV records
by combining the normalized service name and hostname
and obtaining a list of servers for the resulting combination via DNS,
along with their priorities and weights.

- SRV records with the highest priority
  (those with the lowest priority value)
  are resolved as primary servers,
  while other records become backup servers.
  If `backup` is set with `server`,
  SRV records with the highest priority are resolved as backup servers,
  and other records are ignored.
- Weight is analogous to the `weight` parameter of the `server` directive.
  If weight is specified both in the directive itself and in the SRV record,
  the weight set in the directive is used. |

In this example, a lookup is performed for the record `_http._tcp.backend.example.com`:

```nginx
server backend.example.com service=http resolve;
```

| `sid=`id   | Sets the server ID in the group. If the parameter is not specified,
the ID is set as a hexadecimal MD5 hash
of the IP address and port or UNIX socket path.   |
|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|



| `slow_start=`time   | Sets the [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units) for gradual recovery of a returning server's weight
when load balancing with the
[round-robin](#round-robin) or [least_conn](#u-least-conn) method.

If the parameter is set
and the server is considered operational again after a failure
from the perspective of [max_fails](#max-fails) and [upstream_probe (PRO)](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe),
such a server gradually increases to its specified weight
over the given time period.

If the parameter is not set,
in a similar situation
the server immediately starts operating with its specified weight.   |
|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

#### NOTE
If only one `server` is specified in the upstream,
`slow_start` does not work and will be ignored.





### state (PRO)

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `state` file;   |
|------------------------------------------------------------------------------------------|-----------------|
| Default                                                                                  | —               |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream        |

Specifies a file where the list of upstream servers is persistently stored.
When installing from
[our packages](https://en.angie.software//angie/docs/installation/index.md#install-packages),
the directory
`/var/lib/angie/state/` (`/var/db/angie/state/` on FreeBSD)
is created specifically for storing such files
with appropriate access permissions,
and in the configuration you only need to add the file name:

```nginx
upstream backend {

    zone backend 1m;
    state /var/lib/angie/state/;
}
```

The server list here has a format similar to `server`.
The file contents are modified whenever servers are changed in the
[/config/http/upstreams/](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-config-http-upstreams-servers) section
via the configuration API.
The file is read when Angie starts or when the configuration is reloaded.

#### WARNING
To use the `state` directive in an `upstream` block,
there must be no `server` directives in it,
but a shared memory zone ([zone](#u-zone)) is required.





### sticky

#### Versionchanged
Changed in version 1.10.0: PRO

#### Versionchanged
Changed in version 1.11.0.

#### Versionchanged
Changed in version 1.11.0: PRO

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `sticky` cookie name [attr=value]...;

`sticky route` value...;

`sticky learn` `zone=`zone `create=`$create_var1... `lookup=`$lookup_var1... [`header`] [`norefresh`] [`timeout=`time];

`sticky learn` [`zone=`zone] `lookup=`$lookup_var1... `remote_action=`uri `remote_result=`$remote_var [`norefresh`] [`timeout=`time]; (PRO)   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | —                                                                                                                                                                                                                                                                                                                                                               |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                                                                                                                                                                                                                                                                                                                                                        |

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), support for this
directive can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-http_upstream_sticky_module`.

Configures session affinity to bind client sessions to proxied servers
in the mode specified by the first parameter;
to drain servers
that have the `sticky` directive configured,
you can use the `drain` option
in the [server](#u-server) block.

#### WARNING
The `sticky` directive must be used after all directives
that specify a particular load balancing method,
otherwise it will not work.
If it is used alongside the [bind_conn (PRO)](#u-bind-conn) directive,
then `bind_conn` must come after `sticky`.

`cookie` mode

This mode uses cookies to manage sessions.
It's suitable when cookies are already used for session tracking.

The first client request, before any stickiness applies,
is sent to a backend server according to the configured balancing method.
Angie then sets a cookie identifying the chosen server.

The cookie name (`name`) is defined by the `sticky` directive,
and its value corresponds to the [sid](#reresolve)
from the [server](#u-server) directive.
This value is further hashed if [sticky_secret](#u-sticky-secret) is set.

Subsequent requests with this cookie are routed to the server
specified by its [sid](#reresolve).
If the server is unavailable or can't process the request,
another one is chosen via the configured balancing method.

You can assign cookie attributes in the directive;
by default, only `path=/` is set.
Attribute values can contain variables.
To remove an attribute, set it to an empty value: `attr=`.
For example, `sticky cookie path=` omits the `path` attribute.

This example sets a cookie `srv_id` for 1 hour,
using a domain from a variable:

```nginx
upstream backend {
    zone backend 1m;
    server backend1.example.com:8080;
    server backend2.example.com:8080;

    sticky cookie srv_id domain=$my_domain max-age=3600;
}
```

`route` mode

This mode uses predefined route identifiers,
which may come from URLs, cookies, or request arguments.
It's less flexible but good when such identifiers already exist.

The backend server may return a route ID known to both client and server.
This value must match the [sid](#reresolve).

Subsequent requests should carry the route ID,
e.g., via a [cookie](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-cookie) or [query argument](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-arg).

The directive takes a list of strings that may include variables
to extract the route ID. The first non-empty result is matched against
[sid](#reresolve).

In this example, Angie checks the `route` cookie first,
then the `route` query argument:

```nginx
upstream backend {
    zone backend 1m;
    server backend1.example.com:8080 "sid=server 1";
    server backend2.example.com:8080 "sid=server 2";

    sticky route $cookie_route $arg_route;
}
```

`learn` mode

This mode uses a dynamically generated key to assign a client to a backend.
It's flexible and supports session storage in shared memory
and various identifier sources.

A session is created from the backend server's response.
`create` and `lookup` define how to generate and locate sessions,
and both accept multiple variables.

The session ID is the first non-empty variable from `create`.
For example, it may come from a response cookie.

Sessions are stored in shared memory,
defined with `zone name:size`.
If unused for `timeout` duration (default: 1 hour), the session expires.

By default, Angie refreshes sessions on each use.
To disable this, use `norefresh`.

The session ID from a client request is extracted via `lookup`,
using the first non-empty variable listed.
If none is found, it's a new request.

Use `header` to create the session upon receiving response headers
rather than after full response processing.

Example: session created using `examplecookie`:

```nginx
upstream backend {
    zone backend 1m;
    server backend1.example.com:8080;
    server backend2.example.com:8080;

    sticky learn
        create=$upstream_cookie_examplecookie
        lookup=$cookie_examplecookie
        zone=client_sessions:1m;
}
```

`learn` with `remote_action` (PRO)

Use `remote_action` and `remote_result`
to manage session IDs with an external session store.
The shared memory zone acts as a cache;
the external store is authoritative.
`create` is not compatible with `remote_action`.

Sessions expire after `timeout` (default: 1 hour),
regardless of `remote_action`.

By default, Angie refreshes session TTL on each use.
Use `norefresh` to disable that.

`zone` is optional with `remote_action`.
Without it, Angie always queries the external store.

Basic flow:

- Extract session ID from the first non-empty `lookup` variable.
  If none, fall back to standard load balancing.
- If `zone` is set and session exists, use it and stop.
- If no session or no zone, pick a server and make an HTTP subrequest
  to the `remote_action` endpoint with:
  - session ID ([$sticky_sessid](#v-sticky-sessid));
  - server ID from `sid=` or from [$sticky_sid](#v-sticky-sid).

  Send these as HTTP headers (via [proxy_set_header](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-set-header)).
- The remote store responds:
  - 200/201/204 confirms the session; cache it if `zone` is set.
  - 409 signals conflict (if `zone` is set) — session linked to another server.
    Use `remote_result` to extract the corrected server ID.
  - Other status codes or missing server ID — fallback to original server.

`remote_result` uses `upstream_http_*` variables
to read headers from the remote store's response.

Example: session ID comes from `$cookie_bar`,
confirmed via `$upstream_http_x_sticky_sid`:

```nginx
http {

    upstream u1 {
        server srv1;
        server srv2;

        sticky learn zone=sz:1m
            lookup=$cookie_bar
            remote_action=/remote_session
            remote_result=$upstream_http_x_sticky_sid;

        zone z 1m;
    }

    server {

        listen localhost;

        location / {
            proxy_pass http://u1/;
        }

        location /remote_session {
            internal;
            proxy_set_header X-Sticky-Sessid $sticky_sessid;
            proxy_set_header X-Sticky-Sid $sticky_sid;
            proxy_set_header X-Sticky-Last $msec;
            proxy_pass http://remote;
        }
    }
}
```

The following is a simplified configuration example.
The remote store returns the session ID in the `X-Sid` header
and so confirms or overrides Angie's choice:

```nginx
http {

    proxy_cache_path c1 keys_zone=s1:1m;

    upstream tc_0 {
        server 10.0.0.1 sid=web-server-01;
        server 10.0.0.2 sid=web-server-02;

        sticky learn
            lookup=$arg_id
            remote_action=@create_session
            remote_result=$upstream_http_x_sid;
    }

    server {
        listen 127.0.0.1:8080;

        location / {
            proxy_pass http://tc_0/;
        }

        # Request to the remote session store
        location @create_session {
            internal;

            proxy_set_header X-Sticky-Sessid $sticky_sessid;
            proxy_set_header X-Sticky-Sid    $sticky_sid;
            proxy_set_header X-Sticky-Last   $msec;

            proxy_pass http://session_backend;

            proxy_connect_timeout 1s;
            proxy_read_timeout    1s;

            proxy_cache        s1;
            proxy_cache_valid  200 1d;
            proxy_cache_key    "$scheme$proxy_host$request_uri$sticky_sessid";
        }
    }
}
```

Example response:

```none
HTTP/1.1 200 OK
...
X-Sid: web-server-01
X-Session-Backend: backend-pool-1
```

Resulting Angie variables:

- `$upstream_http_x_sid` → `web-server-01`
- `$upstream_http_x_session_backend` → `backend-pool-1`

`remote_result` will use `web-server-01`
to select the matching `sid`.

The `sticky` directive respects upstream server states:

- Servers marked `down` or failing are excluded.
- Servers over `max_conns` limit are skipped.
- `drain` servers may still be selected for new sessions in `sticky` mode when identifiers match.
- Recovered servers are reused automatically.

You can further adjust behavior using
[sticky_secret](#u-sticky-secret) and [sticky_strict](#u-sticky-strict).
If stickiness fails and `sticky_strict` is off,
fallback balancing is used;
if on, the request is rejected.

Each `zone` used in `sticky` must be exclusive to a single `upstream`.
Zones cannot be shared across multiple `upstream` blocks.





### sticky_secret

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `sticky_secret` string;   |
|------------------------------------------------------------------------------------------|---------------------------|
| Default                                                                                  | —                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                  |

Adds the string as the salt value to the MD5 hashing function
for the [sticky](#u-sticky) directive in `cookie` and `route` modes.
The string may contain variables, for example, `$remote_addr`:

```nginx
upstream backend {
    zone backend 1m;
    server backend1.example.com:8080;
    server backend2.example.com:8080;

    sticky cookie cookie_name;
    sticky_secret my_secret.$remote_addr;
}
```

The salt is appended to the value being hashed;
to verify the hashing mechanism independently:

```console
$ echo -n "" | md5sum
```





### sticky_strict

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `sticky_strict` `on` | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------|
| Default                                                                                  | `sticky_strict off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                        |

When enabled, causes Angie to return an HTTP 502 error to the client
if the desired server is unavailable,
rather than using any other available server
as it would when no servers in the upstream are available.





### upstream

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `upstream` name { ... }   |
|------------------------------------------------------------------------------------------|---------------------------|
| Default                                                                                  | —                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                      |

Defines a group of servers. Servers can listen on different ports. In addition, servers listening on TCP and UNIX domain sockets can be mixed.

Example:

```nginx
upstream backend {
    zone backend 1m;
    server backend1.example.com weight=5;
    server 127.0.0.1:8080       max_fails=3 fail_timeout=30s;
    server backup1.example.com  backup;
}
```



By default, requests are distributed between the servers using a weighted round-robin balancing method. In the above example, each 7 requests will be distributed as follows: 5 requests go to backend1.example.com and one request to each of the second and third servers. The distribution is *smooth*: a higher-weight server's requests are spread across the rotation rather than sent in a single burst.

If an error occurs during communication with a server, the request will be passed to the next server, and so on until all of the functioning servers will be tried. If a successful response could not be obtained from any of the servers, the client will receive the result of the communication with the last server.

#### NOTE
By default, a server that fails an occasional attempt
without reaching [max_fails](#max-fails)
temporarily receives a smaller share of requests,
regaining its full share over the requests that follow.
This differs from [slow_start](#slow-start),
which ramps a server back up only after it has been
marked unavailable and has recovered.





### zone

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `zone` name [size];   |
|------------------------------------------------------------------------------------------|-----------------------|
| Default                                                                                  | —                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream              |

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), support for this
directive can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-http_upstream_zone_module`.

Defines the name and size of the shared memory zone that keeps the group's configuration and run-time state that are shared between worker processes. Several groups may share the same zone. In this case, it is enough to specify the size only once.

#### NOTE
The zone's content is only preserved on reload when the configured
`size` is unchanged. Any size change — increase or decrease —
causes the zone to be re-created empty.

#### NOTE
Upstream metrics are collected only when this zone is configured. Without it,
the group does not appear in [/status/http/upstreams/](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-upstreams), the
[HTTP Upstreams Widget](https://en.angie.software//angie/docs/configuration/monitoring.md#console-http-upstreams-widget), or [Prometheus](https://en.angie.software//angie/docs/configuration/modules/http/http_prometheus.md#http-prometheus) output, and no
warning is logged. See [Example configuration](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#example-configuration).



## Built-in Variables

The `http_upstream` module supports the following built-in variables:



### `$sticky_sessid`

Used with `remote_action` in [sticky](#u-sticky);
stores the initial session ID taken from `lookup`.



### `$sticky_sid`

Used with `remote_action` in [sticky](#u-sticky);
stores the server ID previously associated with the session.



### `$upstream_addr`

stores the IP address and port, or the path to the UNIX domain socket of the upstream server. If several servers were contacted during request processing, their addresses are separated by commas, e.g.:

> 192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock

If an internal redirect from one server group to another happens, initiated by `X-Accel-Redirect` or [error_page](https://en.angie.software//angie/docs/configuration/modules/http/index.md#error-page), then the server addresses from different groups are separated by colons, e.g.:

> 192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock : 192.168.10.1:80, 192.168.10.2:80

If a server cannot be selected, the variable keeps the name of the [server group](#u-upstream).



### `$upstream_bytes_received`

number of bytes received from an upstream server. Values from several connections are separated by commas and colons like addresses in the [$upstream_addr](#v-upstream-addr) variable.



### `$upstream_bytes_sent`

number of bytes sent to an upstream server. Values from several connections are separated by commas and colons like addresses in the [$upstream_addr](#v-upstream-addr) variable.



### `$upstream_cache_key`

#### Versionadded
Added in version 1.11.0.

contains the cache key used for the request.



### `$upstream_cache_status`

keeps the status of accessing a response cache. The status can be either
`MISS`, `BYPASS`, `EXPIRED`, `STALE`, `UPDATING`,
`REVALIDATED`, or `HIT`:

- `MISS`: The response is not found in the cache,
  and the request is passed to the upstream server.
- `BYPASS`: The cache is bypassed,
  and the request is passed directly to the upstream server.
- `EXPIRED`: The cached response is stale,
  and a new request is passed to the upstream server to update the content.
- `STALE`: The cached response is stale,
  but is still served to clients
  until the content is eventually updated from the upstream server.
- `UPDATING`: The cached response is stale,
  but is still served to clients
  while the currently ongoing update from the upstream server is in progress.
- `REVALIDATED`: The cached response is stale,
  but was successfully revalidated
  and does not need to be updated from the upstream server.
- `HIT`: The response was taken from the cache.

If the request bypassed the cache without accessing it,
the variable is not set.



### `$upstream_connect_time`

keeps time spent on establishing a connection with the upstream server; the time is kept in seconds with millisecond resolution. In case of SSL, includes time spent on handshake. Times of several connections are separated by commas and colons like addresses in the [$upstream_addr](#v-upstream-addr) variable.



### `$upstream_cookie_`

cookie with the specified name sent by the upstream server in the `Set-Cookie` response header field. Only the cookies from the response of the last server are saved.



### `$upstream_current_addr` (PRO)

#### Versionadded
Added in version 1.12.0: PRO

address of the proxied server selected for the current connection attempt;
unlike [$upstream_addr](#v-upstream-addr), which accumulates the addresses of every server
tried across retries, this variable always holds a single address and is
available immediately after the server is selected, including while
[proxy_bind](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-bind) variables are evaluated.



### `$upstream_header_time`

keeps time spent on receiving the response header from the upstream server; the time is kept in seconds with millisecond resolution. Times of several responses are separated by commas and colons like addresses in the [$upstream_addr](#v-upstream-addr) variable.



### `$upstream_http_`

keep server response header fields. For example, the `Server` response header field is available through the `$upstream_http_server` variable. The rules of converting header field names to variable names are the same as for the variables that start with the `$http_` prefix. Only the header fields from the response of the last server are saved.



### `$upstream_queue_time`

keeps time the request spent in the [queue](#u-queue)
before the next server selection;
the time is kept in seconds with millisecond resolution.
Times of several attempts are separated by commas and colons
like addresses in the [$upstream_addr](#v-upstream-addr) variable.



### `$upstream_request_method`

#### Versionadded
Added in version 1.11.0.

request method used for the upstream request. It can differ from the client
request method when caching converts `HEAD` to `GET` or when
[proxy_method](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-method) is set.



### `$upstream_response_length`

keeps the length of the response obtained from the upstream server; the length is kept in bytes. Lengths of several responses are separated by commas and colons like addresses in the [$upstream_addr](#v-upstream-addr) variable.



### `$upstream_response_time`

keeps time spent on receiving the response from the upstream server; the time is kept in seconds with millisecond resolution. Times of several responses are separated by commas and colons like addresses in the [$upstream_addr](#v-upstream-addr) variable.



### `$upstream_status`

keeps the status code recorded by Angie for each upstream attempt. For DoH
requests, a truncated UDP response is recorded as 426 and an accepted DNS
response as 200. Status codes from several attempts are separated by commas and
colons like addresses in the [$upstream_addr](#v-upstream-addr) variable.



### `$upstream_sticky_status`

Status of sticky requests.

| `""`   | Request sent to an upstream where sticky is not enabled.                                       |
|--------|------------------------------------------------------------------------------------------------|
| `NEW`  | Request does not contain sticky information.                                                   |
| `HIT`  | Request with sticky information sent to the desired server.                                    |
| `MISS` | Request with sticky information sent to a server
selected by the load balancing algorithm. |

Statuses from several connections are separated by commas and colons
like addresses in the [$upstream_addr](#v-upstream-addr) variable.



### `$upstream_trailer_`

keeps fields from the end of the response obtained from the upstream server.



### `$upstream_transport`

#### Versionadded
Added in version 1.12.0.

keeps the transport protocol, `TCP` or `UDP`, used for each
upstream connection attempt. Values from several attempts are separated by
commas and colons like addresses in the [$upstream_addr](#v-upstream-addr) variable.


# https://en.angie.software/angie/docs/configuration/modules/http/http_upstream_probe.md





# Upstream Probe

The module implements active health probes
for [Upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream).



## Configuration Example

```nginx
server {
    listen ...;

    location /backend {
        ...
        proxy_pass http://backend;

        upstream_probe backend_probe
            uri=/probe
            port=10004
            interval=5s
            test=$good
            essential
            fails=3
            passes=3
            max_body=10m
            mode=idle;
    }
}
```



## Directives





### upstream_probe (PRO)

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `upstream_probe` name [`uri=`address] [`port=`number] [`interval=`time] [`method=`method] [`test=`condition] [`essential` [`persistent`]] [`fails=`number] [`passes=`number] [`max_body=`size] [`mode=``always` | `idle` | `onfail`];   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | —                                                                                                                                                                                                                                       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | location                                                                                                                                                                                                                                |

Defines an active health probe for servers within the [upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) groups
that are specified in [proxy_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass), [uwsgi_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-pass), and similar directives
in the same `location` context as the `upstream_probe` directive.
Angie regularly performs requests according to the specified parameters
to each server in the upstream group.

A server passes the probe if the request to it succeeds, considering all
parameter settings of the `upstream_probe` directive and all parameters that
control how upstreams are used by the `location` context where it is defined.
This includes the [proxy_next_upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-next-upstream) and [uwsgi_next_upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-next-upstream)
directives, etc., as well as [proxy_set_header](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-set-header) and so on.

To use the probes,
the upstream must have a shared memory zone ([zone](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone)).
One upstream may be configured with several probes.

The following parameters are accepted:

| `name`       | Mandatory name of the probe.                                                                                                                                                                                                                                                                                                       |
|--------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `uri`        | Request URI to be appended to the argument of [proxy_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass),
[uwsgi_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-pass), etc. By default — `/`.                                         |
| `port`       | Alternative port number for the probe request.                                                                                                                                                                                                                                                                                     |
| `interval`   | [Interval](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units) between probes. By default — `5s`.                                                                                                                                                                                                 |
| `method`     | HTTP method of the probe request. By default — `GET`.                                                                                                                                                                                                                                                                              |
| `test`       | The condition to be checked during the request; defined as a [string with variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables).
If variable substitution yields `""` or `"0"`,
the probe fails.                                                                                  |
| `essential`  | If set, the initial state of the server is subject to verification
and client requests are not forwarded to it until the probe is passed.                                                                                                                                                                                      |
| `persistent` | Setting this parameter requires enabling `essential` first;
`persistent` servers that were working prior to a
[configuration reload](https://en.angie.software//angie/docs/configuration/configfile.md#configfile-reloading)
start receiving requests without being required to pass this probe first.                 |
| `fails`      | Number of consecutive failed requests that
renders the server unhealthy. By default — 1.                                                                                                                                                                                                                                       |
| `passes`     | Number of consecutive successful requests that
renders the server healthy. By default — 1.                                                                                                                                                                                                                                     |
| `max_body`   | Maximum amount of memory for the response body. By default — `256k`.                                                                                                                                                                                                                                                               |
| `mode`       | Probe mode, depending on the servers' health:

- `always` — servers are probed regardless of their state;
- `idle` — probes affect unhealthy servers and servers where
  `interval` has elapsed since the last client request.
- `onfail` — only unhealthy servers are probed.

By default — `always`. |

Example:

```nginx
upstream backend {
    zone backend 1m;

    server backend1.example.com;
    server backend2.example.com;
}

map $upstream_status $good {
    200     "1";
}

server {
    listen ...;

    location /backend {
        ...
        proxy_pass http://backend;

        upstream_probe backend_probe
            uri=/probe
            port=10004
            interval=5s
            test=$good
            essential
            persistent
            fails=3
            passes=3
            max_body=10m
            mode=idle;
    }
}
```

Details of probe operation:

- Initially, the server won't receive client requests
  until it passes *all* `essential` probes configured for it
  (skipping `persistent` ones if the configuration was reloaded
  and the server was deemed healthy prior to that).
  If there are no such probes, the server is considered healthy.
- The server is considered unhealthy and won't receive client requests
  if *any* of the probes configured for it hits its `fails` threshold
  or the server itself reaches the [max_fails](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) threshold.
- For an unhealthy server to be considered healthy again,
  *all* probes configured for it must reach their respective `passes` thresholds;
  after that, the [max_fails](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) threshold is considered.



## Built-in Variables

The `http_upstream_probe` module supports the following built-in variables:



### `$upstream_probe` (PRO)

Name of the currently active [upstream_probe](#u-upstream-probe).



### `$upstream_probe_body` (PRO)

Server response body
received during an [upstream_probe](#u-upstream-probe);
its size is limited by `max_body`.


# https://en.angie.software/angie/docs/configuration/modules/http/http_userid.md





# UserID

The module sets cookies suitable for client identification. Received and set cookies can be logged using the built-in variables [$uid_got](#v-uid-got) and [$uid_set](#v-uid-set). This module is compatible with the [mod_uid](http://www.lexa.ru/programs/mod-uid.html) module for Apache.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by
default; it can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-http_userid_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
userid         on;
userid_name    uid;
userid_domain  example.com;
userid_path    /;
userid_expires 365d;
userid_p3p     'policyref="/w3c/p3p.xml", CP="CUR ADM OUR NOR STA NID"';
```



## Directives





### userid

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `userid` `on` | `v1` | `log` | `off`;   |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| Default                                                                                  | `userid off;`                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                  |

Enables or disables setting cookies and logging the received cookies:

| `on`   | enables the setting of version 2 cookies and logging of the received cookies;   |
|--------|---------------------------------------------------------------------------------|
| `v1`   | enables the setting of version 1 cookies and logging of the received cookies;   |
| `log`  | disables the setting of cookies, but enables logging of the received cookies;   |
| `off`  | disables the setting of cookies and logging of the received cookies.            |





### userid_domain

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `userid_domain` name | `none`;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | `userid_domain none;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location           |

Defines a domain for which the cookie is set. The `none` parameter disables setting of a domain for the cookie.





### userid_expires

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `userid_expires` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units) | `max` | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `userid_expires off;`                                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                          |

Sets a time during which a browser should keep the cookie. The parameter `max` will cause the cookie to expire on "31 Dec 2037 23:55:55 GMT". The parameter `off` will cause the cookie to expire at the end of a browser session.





### userid_flags

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `userid_flags` `off` | flag ...;   |
|------------------------------------------------------------------------------------------|------------------------------------|
| Default                                                                                  | `userid_flags off;`                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location             |

If the parameter is not `off`, defines one or more additional flags for
the cookie: `secure`, `httponly`, `samesite=strict`,
`samesite=lax`, `samesite=none`.





### userid_mark

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `userid_mark` letter | digit | = | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| Default                                                                                  | `userid_mark off;`                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                      |

If the parameter is not `off`, enables the cookie marking mechanism and sets the character used as a mark. This mechanism is used to add or change [userid_p3p](#userid-p3p) and/or a cookie expiration time while preserving the client identifier. A mark can be any letter of the English alphabet (case-sensitive), digit, or the "=" character.

If the mark is set, it is compared with the first padding symbol in the base64 representation of the client identifier passed in a cookie. If they do not match, the cookie is resent with the specified mark, expiration time, and `P3P` header.





### userid_name

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `userid_name` name;    |
|------------------------------------------------------------------------------------------|------------------------|
| Default                                                                                  | `userid_name uid;`     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location |

Sets the cookie name.





### userid_p3p

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `userid_p3p` string | `none`;   |
|------------------------------------------------------------------------------------------|---------------------------------|
| Default                                                                                  | `userid_p3p none;`              |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location          |

Sets a value for the `P3P` header field that will be sent along with the cookie. If the directive is set to the special value `none`, the `P3P` header will not be sent in a response.





### userid_path

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `userid_path` path;    |
|------------------------------------------------------------------------------------------|------------------------|
| Default                                                                                  | `userid_path /;`       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location |

Defines a path for which the cookie is set.





### userid_service

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `userid_service` number;                   |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| Default                                                                                  | `userid_service IP address of the server;` |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                     |

If identifiers are issued by multiple servers (services), each service should be assigned its own `number` to ensure that client identifiers are unique. For version 1 cookies, the default value is zero. For version 2 cookies, the default value is the number composed from the last four octets of the server's IP address.



## Built-in Variables



### `$uid_got`

The cookie name and received client identifier.



### `$uid_reset`

If the variable is set to a non-empty string that is not `0`, the client identifiers are reset. The special value `log` additionally leads to the output of messages about the reset identifiers to the [error_log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log).



### `$uid_set`

The cookie name and sent client identifier.


# https://en.angie.software/angie/docs/configuration/modules/http/http_uwsgi.md





# uWSGI

Allows passing requests to a uWSGI server.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by
default; it can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-http_uwsgi_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
location / {
    include    uwsgi_params;
    uwsgi_pass localhost:9000;
}
```



## Directives





### uwsgi_bind

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_bind` address [`transparent`] | `off`;   |
|------------------------------------------------------------------------------------------|-------------------------------------------------|
| Default                                                                                  | —                                               |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                          |

Makes outgoing connections to a uWSGI server originate from the specified local IP address with an optional port. Parameter value can contain [variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables). The special value `off` cancels the effect of the uwsgi_bind directive inherited from the previous configuration level, which allows the system to auto-assign the local IP address and port.

By default, this value is evaluated once when the request is initialized, before
a uWSGI server is selected. In Angie PRO, evaluation happens after each uWSGI
server selection (including retries), so the bind address can depend on the
selected server; for example, via the `$upstream_current_addr` variable.
If the evaluated value is empty, no binding is made.

The `transparent` parameter allows outgoing connections to a uWSGI server
originate from a non-local IP address, for example, from a real IP address of a
client:

```nginx
uwsgi_bind $remote_addr transparent;
```

In order for this parameter to work, it is usually necessary to run Angie worker processes with the [superuser](https://en.angie.software//angie/docs/configuration/modules/core.md#user) privileges. On Linux it is not required as if the `transparent` parameter is specified, worker processes inherit the CAP_NET_RAW capability from the master process.

#### NOTE
It is necessary to configure kernel routing table to intercept network traffic from the uWSGI server.





### uwsgi_buffer_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_buffer_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `uwsgi_buffer_size 4k|8k;`                                                                                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                             |

Sets the size of the buffer used for reading the first part of the response received from the uWSGI server. This part usually contains a small response header. By default, the buffer size is equal to one memory page. This is either 4K or 8K, depending on a platform. It can be made smaller, however.





### uwsgi_buffering

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_buffering` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-----------------------------------|
| Default                                                                                  | `uwsgi_buffering on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location            |

Enables or disables buffering of responses from the uWSGI server.

| `on`   | Angie receives a response from the uWSGI server as soon as possible, saving it into the buffers set by the [uwsgi_buffer_size](#uwsgi-buffer-size) and [uwsgi_buffers](#uwsgi-buffers) directives. Sending to the client is performed in parallel: filled buffers are passed for sending, but their total size is limited by [uwsgi_busy_buffers_size](#uwsgi-busy-buffers-size). If a buffer is not completely filled, it is not passed for sending unless it contains the last part of the response. Therefore, buffered reading is not suitable when you need immediate delivery of every few bytes. If the whole response does not fit into memory, a part of it can be saved to a [temporary file](#uwsgi-temp-path) on the disk. Writing to temporary files is controlled by the [uwsgi_max_temp_file_size](#uwsgi-max-temp-file-size) and [uwsgi_temp_file_write_size](#uwsgi-temp-file-write-size) directives.   |
|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off`  | The response is passed to a client immediately as it is received. Angie works in a "read — send" loop and does not wait for the buffer to fill completely: for example, 10 bytes read from a 4K buffer are sent right away. At the same time, if the entire response fits into the buffer, Angie can read it in full. The maximum size of the data that Angie can receive from the server at a time is set by the [uwsgi_buffer_size](#uwsgi-buffer-size) directive. With `off`, [uwsgi_limit_rate](#uwsgi-limit-rate) does not work.                                                                                                                                                                                                                                                                                                                                                                                    |

Buffering can also be enabled or disabled by passing "yes" or "no" in the `X-Accel-Buffering` response header field. This capability can be disabled using the [uwsgi_ignore_headers](#uwsgi-ignore-headers) directive.





### uwsgi_buffers

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_buffers` number [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `uwsgi_buffers 8 4k | 8k;`                                                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                |

Sets the number and size of the buffers used for reading a response from the uWSGI server, for a single connection.

By default, the buffer size is equal to one memory page. This is either 4K or 8K, depending on a platform.





### uwsgi_busy_buffers_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_busy_buffers_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `uwsgi_busy_buffers_size 8k | 16k;`                                                                                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                   |

When [buffering](#uwsgi-buffering) of responses from the uWSGI server is enabled, limits the total size of buffers that can be busy sending a response to the client while the response is not yet fully read. In the meantime, the rest of the buffers can be used for reading the response and, if needed, buffering part of the response to a temporary file.

By default, size is limited by the size of two buffers set by the [uwsgi_buffer_size](#uwsgi-buffer-size) and [uwsgi_buffers](#uwsgi-buffers) directives.





### uwsgi_cache

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_cache` zone | `off`;   |
|------------------------------------------------------------------------------------------|-------------------------------|
| Default                                                                                  | `uwsgi_cache off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location        |

Defines a shared memory zone used for caching. The same zone can be used in several places. Parameter value can contain variables.

| `off`   | disables caching inherited from the previous configuration level.   |
|---------|---------------------------------------------------------------------|

#### NOTE
When using [uwsgi_cache](#uwsgi-cache),
you typically need to also set the [uwsgi_cache_valid](#uwsgi-cache-valid) directive
to explicitly specify the caching time for responses.
If it's not set, Angie doesn't use default values
but determines the response caching time
based on HTTP response headers from the server in the following priority order:

1. The `X-Accel-Expires` header (highest priority).
2. The `Cache-Control` header
   with `max-age` or `s-maxage` parameters.
3. The `Expires` header.

If none of these headers contain valid values or are not present at all,
the response will not be cached because its expiration time cannot be determined.





### uwsgi_cache_background_update

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_cache_background_update` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-------------------------------------------------|
| Default                                                                                  | `uwsgi_cache_background_update off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                          |

Allows starting a background subrequest to update an expired cache item, while a stale cached response is returned to the client.

#### WARNING
Note that it is necessary to [allow](#uwsgi-cache-use-stale-updating) the usage of a stale cached response when it is being updated.





### uwsgi_cache_bypass

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_cache_bypass` ...;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| Default                                                                                  | —                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location      |

Defines conditions under which the response will not be taken from a cache. If at least one value of the string parameters is not empty and is not equal to "0" then the response will not be taken from the cache:

```nginx
uwsgi_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
uwsgi_cache_bypass $http_pragma    $http_authorization;
```

Parameter values can contain variables.

Can be used along with the [uwsgi_no_cache](#uwsgi-no-cache) directive.





### uwsgi_cache_key

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_cache_key` string;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| Default                                                                                  | —                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location      |

Defines a key for caching. The key can contain variables. For example

```nginx
uwsgi_cache_key localhost:9000$request_uri;
```





### uwsgi_cache_lock

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_cache_lock` `on` | `off`;   |
|------------------------------------------------------------------------------------------|------------------------------------|
| Default                                                                                  | `uwsgi_cache_lock off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location             |

When enabled, only one request at a time will be allowed to populate a new cache element identified according to the [uwsgi_cache_key](#uwsgi-cache-key) directive by passing a request to a uWSGI server. Other requests of the same cache element will either wait for a response to appear in the cache or the cache lock for this element to be released, up to the time set by the [uwsgi_cache_lock_timeout](#uwsgi-cache-lock-timeout) directive.





### uwsgi_cache_lock_age

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_cache_lock_age` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `uwsgi_cache_lock_age 5s;`                                                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                |

If the last request passed to the uWSGI server for populating a new cache element has not completed for the specified time, one more request may be passed to the uWSGI server.





### uwsgi_cache_lock_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_cache_lock_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `uwsgi_cache_lock_timeout 5s;`                                                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                    |

Sets a timeout for [uwsgi_cache_lock](#uwsgi-cache-lock). When the time expires, the request will be passed to the uWSGI server, however, the response will not be cached.





### uwsgi_cache_max_range_offset

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_cache_max_range_offset` number;   |
|------------------------------------------------------------------------------------------|------------------------------------------|
| Default                                                                                  | —                                        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                   |

Sets an offset in bytes for byte-range requests. If the range is beyond the offset, the range request will be passed to the uWSGI server and the response will not be cached.





### uwsgi_cache_methods

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_cache_methods` `GET` | `HEAD` | `POST` ...;   |
|------------------------------------------------------------------------------------------|------------------------------------------------------|
| Default                                                                                  | `uwsgi_cache_methods GET HEAD;`                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                               |

If the client request method is listed in this directive then the response will be cached. "GET" and "HEAD" methods are always added to the list, though it is recommended to specify them explicitly. See also the [uwsgi_no_cache](#uwsgi-no-cache) directive.





### uwsgi_cache_min_uses

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_cache_min_uses` number;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | `uwsgi_cache_min_uses 1;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location           |

Sets the number of requests after which the response will be cached.

#### WARNING
Cache metadata is stored in shared memory. Manually deleting cache files does
not reset the counters and may lead to unpredictable behavior. To
completely reset the cache, stop the server, delete the cache directory, and start again.

#### NOTE
Third-party cache purge modules (e.g., [Cache Purge](https://en.angie.software//angie/docs/configuration/modules/external-modules/cache-purge.md#external-cache-purge)) only delete
files but do not reset the uwsgi_cache_min_uses counter. The directive
is intended to protect the cache from pollution by infrequent requests, and resetting
the counter on purge could negatively impact performance.





### uwsgi_cache_path

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_cache_path` path [`levels=`levels] [`use_temp_path=``on` | `off`] `keys_zone=`name:size[:`file=`file] [`inactive=`time] [`max_size=`size] [`min_free=`size] [`manager_files=`number] [`manager_sleep=`time] [`manager_threshold=`time] [`loader_files=`number] [`loader_sleep=`time] [`loader_threshold=`time];   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | —                                                                                                                                                                                                                                                                                                                        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                                                                                                                                                                                                                                                                                                                     |

Sets the path and other parameters of a cache. Cache data are stored in files. The file name in a cache is a result of applying the MD5 function to the [cache key](#uwsgi-cache-key).

| `levels`   | defines hierarchy levels of a cache: from 1 to 3, each level accepts values 1 or 2.   |
|------------|---------------------------------------------------------------------------------------|

For example, in the following configuration:

```nginx
uwsgi_cache_path /data/angie/cache levels=1:2 keys_zone=one:10m;
```

file names in a cache will look like this:

```nginx
/data/angie/cache/c/29/b7f54b2df7773722d382f4809d65029c
```

A cached response is first written to a temporary file, and then the file is renamed. Temporary files and the cache can be put on different file systems. However, be aware that in this case a file is copied across two file systems instead of the cheap renaming operation. It is thus recommended that for any given location both cache and a directory holding temporary files are put on the same file system.

| `use_temp_path=on` | `off`   | determines the directory to be used for temporary files                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
|------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `on`                         | If the parameter is not specified or set to `on`, the directory specified by the [uwsgi_temp_path](#uwsgi-temp-path) directive for the given location will be used                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `off`                        | temporary files will be placed directly in the cache directory                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `keys_zone`                  | Sets the name and size of the shared memory zone for storing all active keys and information about data. Cache metadata is stored in shared memory.

The zone size is specified in bytes and must be at least two system
memory pages. The `k` and `m` suffixes are also accepted;
unlike `max_size`, this parameter does not accept `g`.

A zone of 1 megabyte is sufficient to store about 8000 keys.

When an optional file is specified with `keys_zone`,
Angie dumps the contents of this zone to disk
when the main process terminates
and attempts to restore it at the same memory address
on the next [startup](https://en.angie.software//angie/docs/configuration/runtime.md#runtime)
or after [binary upgrade](https://en.angie.software//angie/docs/configuration/runtime.md#service-upgrade),
to ensure more reliable data persistence
and reduce cache loading time.

If the zone cannot be restored due to a change in its size,
binary version incompatibility, or other reasons,
Angie will log a warning (`failed to restore zone at address`)
and will not use the zone restoration mechanism.
Instead, the incompatible file will be renamed to `.old`;
you can either delete it,
or restore its name and revert Angie to the configuration and version
in which this file was originally created.

#### WARNING
Make sure the path to the file is specified correctly
and has the necessary access permissions for Angie to use,
and is protected from unauthorized access;
relative paths are based on the [prefix](https://en.angie.software//angie/docs/installation/sourcebuild.md#paths). |
| `inactive`                   | If cached data is not accessed within the time set by this parameter, it is removed, regardless of its freshness; each access resets this timer. This differs from the size-based eviction performed by the **cache manager** described below: inactivity-based removal applies even when the cache is below `max_size`, and it ignores the validity periods configured with [uwsgi_cache_valid](#uwsgi-cache-valid).

By default, `inactive` is 10 minutes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

A special **cache manager** process monitors the maximum cache size and the minimum amount of free space on the file system with cache, and when the size is exceeded or there is not enough free space, it removes the least recently used data. The data is removed in iterations.

| `max_size`          | maximum threshold value for cache size

The value is specified in bytes; the `k`, `m`, and
`g` suffixes are also accepted.
By default, the cache size is not limited.                                                                                                                                                                                                          |
|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `min_free`          | minimum threshold value for free space on the file system with cache

The value is specified in the same units as `max_size`.
The default value `0` disables free space monitoring.

On platforms that do not support querying file system statistics,
the parameter is ignored, and Angie logs the warning
`min_free is not supported on this platform, ignored`. |
| `manager_files`     | maximum number of cache items deleted in one iteration

Default: `100`                                                                                                                                                                                                                                                                                                                 |
| `manager_threshold` | limits the time of one iteration

Default: `200` milliseconds                                                                                                                                                                                                                                                                                                                          |
| `manager_sleep`     | time for which a pause is maintained between iterations

Default: `50` milliseconds                                                                                                                                                                                                                                                                                                    |

One minute after Angie starts, a special **cache loader** process is activated, which loads information about previously cached data stored on the filesystem into the cache zone. Loading also occurs in iterations.

| `loader_files`     | maximum number of cache items to load in one iteration

Default: `100`              |
|--------------------|---------------------------------------------------------------------------------------------|
| `loader_threshold` | limits the time of one iteration

Default: `200` milliseconds                       |
| `loader_sleep`     | time for which a pause is maintained between iterations

Default: `50` milliseconds |





### uwsgi_cache_revalidate

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_cache_revalidate` `on` | `off`;   |
|------------------------------------------------------------------------------------------|------------------------------------------|
| Default                                                                                  | `uwsgi_cache_revalidate off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                   |

Enables revalidation of expired cache items using conditional requests with the `If-Modified-Since` and `If-None-Match` header fields.





### uwsgi_cache_use_stale

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_cache_use_stale` `error` | `timeout` | `invalid_header` | `updating` | `http_500` | `http_503` |  `http_403` | `http_404` | `http_429` | `off` ...;   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `uwsgi_cache_use_stale off;`                                                                                                                                 |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                                                       |

Determines in which cases a stale cached response can be used. The directive's parameters match the parameters of the [uwsgi_next_upstream](#uwsgi-next-upstream) directive.

| `error`    | Permits using a stale cached response if a uwsgi server to process a request cannot be selected.                                                                                        |
|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `updating` | Additional parameter, permits using a stale cached response if it is currently being updated. This allows minimizing the number of accesses to uwsgi servers when updating cached data. |

Using a stale cached response can also be enabled directly in the response header for a specified number of seconds after the response became stale:

* The [stale-while-revalidate](https://datatracker.ietf.org/doc/html/rfc5861#section-3) extension of the `Cache-Control` header field permits using a stale cached response if it is currently being updated.
* The [stale-if-error](https://datatracker.ietf.org/doc/html/rfc5861#section-4) extension of the `Cache-Control` header field permits using a stale cached response in case of an error.

#### NOTE
This method has lower priority than setting directive parameters.

To minimize the number of requests to uwsgi servers when populating a new cache element, the [uwsgi_cache_lock](#uwsgi-cache-lock) directive can be used.





### uwsgi_cache_valid

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_cache_valid` [code ...] [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | —                                                                                                                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                        |

Sets caching time for different response codes. For example, the following directives

```nginx
uwsgi_cache_valid 200 302 10m;
uwsgi_cache_valid 404      1m;
```

set 10 minutes of caching for responses with codes 200 and 302 and 1 minute for responses with code 404.

If only caching time is specified,

```nginx
uwsgi_cache_valid 5m;
```

then only 200, 301, and 302 responses are cached.

In addition, it can be specified to cache any responses using the `any` parameter:

```nginx
uwsgi_cache_valid 200 302 10m;
uwsgi_cache_valid 301      1h;
uwsgi_cache_valid any      1m;
```

#### NOTE
Caching parameters can also be set directly in the response header. This method has higher priority than setting caching time using the directive.

* The `X-Accel-Expires` header field sets caching time of a response in seconds. The value 0 disables caching for a response. If the value starts with the @ prefix, it sets an absolute time in seconds since Epoch, up to which the response may be cached.
* If the header does not include the `X-Accel-Expires` field, caching parameters are determined by the `Expires` or `Cache-Control` header fields.
* A response with the `Set-Cookie` header field will not be cached.
* A response with the `Vary` header field with the special value "\*" will not be cached. A response with the `Vary` header field with another value will be cached taking into account the corresponding request header fields.

Processing of one or more of these header fields can be disabled using the [uwsgi_ignore_headers](#uwsgi-ignore-headers) directive.





### uwsgi_connect_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_connect_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `uwsgi_connect_timeout 60s;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                 |

Defines a timeout for establishing a connection with a uwsgi server. It should be noted that this timeout cannot usually exceed 75 seconds.





### uwsgi_connection_drop

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_connection_drop` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units) | `on` | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `uwsgi_connection_drop off;`                                                                                                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                                |

Enables termination of all active connections to the proxied server after it has been
removed from the group or marked as permanently unavailable by a [reresolve](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve) process or the [API command](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-config-methods)
`DELETE`.
Idle connections in the [cache](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive) are not affected.

A connection is terminated when the next read or write event is processed for either the client or the proxied server.

Setting time enables a connection termination [timeout](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);
with `on` set, connections are dropped immediately.





### uwsgi_force_ranges

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_force_ranges` `on` | `off`;   |
|------------------------------------------------------------------------------------------|--------------------------------------|
| Default                                                                                  | `uwsgi_force_ranges off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location               |

Enables byte-range support for both cached and uncached responses from a uwsgi server regardless of the presence of the `Accept-Ranges` field in these responses.





### uwsgi_hide_header

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_hide_header` field;   |
|------------------------------------------------------------------------------------------|------------------------------|
| Default                                                                                  | —                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location       |

By default, Angie does not pass the header fields `Date`, `Server`, `X-Pad`, and `X-Accel-...` from the response of a uwsgi server to a client. The uwsgi_hide_header directive sets additional fields that will not be passed. If, conversely, the passing of fields needs to be permitted, the [uwsgi_pass_header](#uwsgi-pass-header) directive can be used.





### uwsgi_ignore_client_abort

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_ignore_client_abort` `on` | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| Default                                                                                  | `uwsgi_ignore_client_abort off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                      |

Determines whether the connection with a uwsgi server should be closed when a client closes the connection without waiting for a response.





### uwsgi_ignore_headers

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_ignore_headers` field ...;   |
|------------------------------------------------------------------------------------------|-------------------------------------|
| Default                                                                                  | —                                   |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location              |

Disables processing of certain response header fields from the uwsgi server. The following fields can be ignored: `X-Accel-Redirect`, `X-Accel-Expires`, `X-Accel-Limit-Rate`, `X-Accel-Buffering`, `X-Accel-Charset`, `Expires`, `Cache-Control`, `Set-Cookie`, and `Vary`.

If not disabled, processing of these header fields has the following effect:

* `X-Accel-Expires`, `Expires`, `Cache-Control`, `Set-Cookie`, and `Vary` set the parameters of response [caching](#uwsgi-cache-valid);
* `X-Accel-Redirect` performs an [internal redirect](https://en.angie.software//angie/docs/configuration/modules/http/index.md#internal) to the specified URI;
* `X-Accel-Limit-Rate` sets the [rate limit](https://en.angie.software//angie/docs/configuration/modules/http/index.md#limit-rate) for transmission of a response to a client;
* `X-Accel-Buffering` enables or disables [buffering](#uwsgi-buffering) of a response;
* `X-Accel-Charset` sets the desired [charset](https://en.angie.software//angie/docs/configuration/modules/http/http_charset.md#id1) of a response.





### uwsgi_intercept_errors

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_intercept_errors` `on` | `off`;   |
|------------------------------------------------------------------------------------------|------------------------------------------|
| Default                                                                                  | `uwsgi_intercept_errors off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                   |

Determines whether uwsgi server responses with codes greater than or equal to 300 should be passed to a client or be intercepted and redirected to Angie for processing with the [error_page](https://en.angie.software//angie/docs/configuration/modules/http/index.md#error-page) directive.





### uwsgi_limit_rate

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_limit_rate` rate;   |
|------------------------------------------------------------------------------------------|----------------------------|
| Default                                                                                  | `uwsgi_limit_rate 0;`      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location     |

Limits the speed of reading the response from the uwsgi server.
The rate is specified in bytes per second and can contain variables.

| `0`   | disables rate limiting   |
|-------|--------------------------|

#### NOTE
The limit is set per a request, and so if Angie simultaneously opens two connections to the uwsgi server, the overall rate will be twice as much as the specified limit. The limitation works only if [buffering](#uwsgi-buffering) of responses from the uwsgi server is enabled.





### uwsgi_max_temp_file_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_max_temp_file_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `uwsgi_max_temp_file_size 1024m;`                                                                                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                    |

When [buffering](#uwsgi-buffering) of responses from the uwsgi server is enabled, and the whole response does not fit into the buffers set by the [uwsgi_buffer_size](#uwsgi-buffer-size) and [uwsgi_buffers](#uwsgi-buffers) directives, a part of the response can be saved to a temporary file. This directive sets the maximum size of the temporary file. The size of data written to the temporary file at a time is set by the [uwsgi_temp_file_write_size](#uwsgi-temp-file-write-size) directive.

| `0`   | disables buffering of responses to temporary files   |
|-------|------------------------------------------------------|

#### NOTE
This restriction does not apply to responses that will be [cached](#uwsgi-cache) or [stored on disk](#uwsgi-store).





### uwsgi_modifier1

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_modifier1` number;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| Default                                                                                  | `uwsgi_modifier1 0;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location      |

Sets the value of the modifier1 field in the uwsgi packet header.





### uwsgi_modifier2

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_modifier2` number;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| Default                                                                                  | `uwsgi_modifier2 0;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location      |

Sets the value of the modifier2 field in the uwsgi packet header.





### uwsgi_next_upstream

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_next_upstream` `error` | `timeout` | `invalid_header` | `http_500` | `http_503` | `http_403` | `http_404` | `http_429` | `non_idempotent` | `off` ...;   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `uwsgi_next_upstream error timeout;`                                                                                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                                                          |

Specifies in which cases a request should be passed to the next server in the [upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream) group:

| `error`          | a connection error, request transmission error, or response header reading error occurred;                                                                                                                                                                                                           |
|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `timeout`        | a timeout occurred during connection establishment, request transmission, or response header reading;                                                                                                                                                                                                |
| `invalid_header` | the server returned an empty or invalid response;                                                                                                                                                                                                                                                    |
| `http_500`       | the server returned a response with code 500;                                                                                                                                                                                                                                                        |
| `http_503`       | the server returned a response with code 503;                                                                                                                                                                                                                                                        |
| `http_403`       | the server returned a response with code 403;                                                                                                                                                                                                                                                        |
| `http_404`       | the server returned a response with code 404;                                                                                                                                                                                                                                                        |
| `http_429`       | the server returned a response with code 429;                                                                                                                                                                                                                                                        |
| `non_idempotent` | normally, requests with [non-idempotent](https://datatracker.ietf.org/doc/html/rfc7231#section-4.2.2) methods (`POST`, `LOCK`, `PATCH`) are not passed to another server if a request to an upstream server has already been sent; enabling this parameter explicitly allows retrying such requests; |
| `off`            | disables passing a request to the next server.                                                                                                                                                                                                                                                       |

#### NOTE
It should be understood that passing a request to the next server is only possible if nothing has been sent to the client yet. That is, if an error or timeout occurs in the middle of the transmission of a response, fixing this is impossible.

The directive also defines what is considered an [unsuccessful attempt](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) of communication with a server.

| `error`

`timeout`

`invalid_header`   | are always considered unsuccessful attempts, even if they are not specified in the directive   |
|--------------------------------------------------------|------------------------------------------------------------------------------------------------|
| `http_500`

`http_503`

`http_429`     | are considered unsuccessful attempts only if they are specified in the directive               |
| `http_403`

`http_404`                         | are never considered unsuccessful attempts                                                     |

Passing a request to the next server can be limited by the [number of tries](#uwsgi-next-upstream-tries) and by [time](#uwsgi-next-upstream-timeout).





### uwsgi_next_upstream_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_next_upstream_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `uwsgi_next_upstream_timeout 0;`                                                                                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                       |

Limits the time during which a request can be passed to the [next](#uwsgi-next-upstream) server.

| `0`   | turns off this limitation   |
|-------|-----------------------------|





### uwsgi_next_upstream_tries

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_next_upstream_tries` number;   |
|------------------------------------------------------------------------------------------|---------------------------------------|
| Default                                                                                  | `uwsgi_next_upstream_tries 0;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                |

Limits the number of possible tries for passing a request to the [next](#uwsgi-next-upstream) server.

| `0`   | turns off this limitation   |
|-------|-----------------------------|





### uwsgi_no_cache

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_no_cache` string ...;   |
|------------------------------------------------------------------------------------------|--------------------------------|
| Default                                                                                  | —                              |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location         |

Defines conditions under which the response will not be saved to a cache. If at least one value of the string parameters is not empty and is not equal to "0" then the response will not be saved:

```nginx
uwsgi_no_cache $cookie_nocache $arg_nocache$arg_comment;
uwsgi_no_cache $http_pragma    $http_authorization;
```

Parameter values can contain variables.

Can be used along with the [uwsgi_cache_bypass](#uwsgi-cache-bypass) directive.





### uwsgi_param

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_param` parameter value [`if_not_empty`];   |
|------------------------------------------------------------------------------------------|---------------------------------------------------|
| Default                                                                                  | —                                                 |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                            |

Sets a parameter that should be passed to the uwsgi server. The value can contain variables. These directives are inherited from the previous configuration level if and only if there are no `uwsgi_param` directives defined on the current level.

Standard [CGI environment variables](https://datatracker.ietf.org/doc/html/rfc3875#section-4.1) should be provided as uwsgi headers, see the `uwsgi_params` file provided in the distribution:

```nginx
location / {
    include uwsgi_params;
#    ...
}
```

In the standard `uwsgi_params` file, `REQUEST_METHOD` is set to
`$upstream_request_method`.

If the directive is specified with `if_not_empty` then such a parameter will be passed to the server only if its value is not empty:

```nginx
uwsgi_param HTTPS $https if_not_empty;
```





### uwsgi_pass

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_pass` [protocol://] address;   |
|------------------------------------------------------------------------------------------|---------------------------------------|
| Default                                                                                  | —                                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | location, if in location              |

Sets the protocol and address of a uwsgi server. As a protocol, `uwsgi` or `suwsgi` (secured uwsgi, uwsgi over SSL) can be specified. The address can be specified as a domain name or IP address, and a port:

```nginx
uwsgi_pass localhost:9000;
uwsgi_pass uwsgi://localhost:9000;
uwsgi_pass suwsgi://[2001:db8::1]:9090;
```

or as a UNIX domain socket path specified after the word `unix` and enclosed in colons:

```nginx
uwsgi_pass unix:/tmp/uwsgi.socket;
```

If a domain name resolves to several addresses, all of them will be used in a round-robin fashion. In addition, an address can be specified as a [server group](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream).

Parameter value can contain variables. In this case, if an address is specified as a domain name, the name is searched among the described server groups, and, if not found, is determined using a [resolver](https://en.angie.software//angie/docs/configuration/modules/http/index.md#resolver).

#### NOTE
If `uwsgi_pass` is specified in a `location` with a trailing slash in the prefix
(for example, `location /name/`),
and the [auto_redirect](https://en.angie.software//angie/docs/configuration/modules/http/index.md#auto-redirect) directive is set to `default`,
requests without a trailing slash will be redirected (`/name -> /name/`).





### uwsgi_pass_header

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_pass_header` field ...;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | —                                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location           |

Permits passing [otherwise disabled](#uwsgi-hide-header) header fields from a uwsgi server to a client.





### uwsgi_pass_request_body

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_pass_request_body` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-------------------------------------------|
| Default                                                                                  | `uwsgi_pass_request_body on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                    |

Indicates whether the original request body is passed to the uwsgi server. See also the [uwsgi_pass_request_headers](#uwsgi-pass-request-headers) directive.





### uwsgi_pass_request_headers

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_pass_request_headers` `on` | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------------------------|
| Default                                                                                  | `uwsgi_pass_request_headers on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                       |

Enables or disables passing of header fields from the original request to the uwsgi server. See also the [uwsgi_pass_request_body](#uwsgi-pass-request-body) directive.





### uwsgi_read_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_read_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `uwsgi_read_timeout 60s;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                              |

Defines a timeout for reading a response from the uwsgi server. The timeout is set only between two successive read operations, not for the transmission of the whole response. If the uwsgi server does not transmit anything within this time, the connection is closed.





### uwsgi_request_buffering

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_request_buffering` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-------------------------------------------|
| Default                                                                                  | `uwsgi_request_buffering on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                    |

Enables or disables buffering of a client request body.

| `on`   | The request body is fully [read](https://en.angie.software//angie/docs/configuration/modules/http/index.md#client-body-buffer-size) from the client before sending the request to the uwsgi server.                      |
|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off`  | The request body is sent to the uwsgi server immediately as it is received. In this case, the request cannot be passed to the [next server](#uwsgi-next-upstream) if Angie has already started sending the request body. |

When HTTP/1.1 chunked transfer encoding is used to send the original request body, then the request body will be buffered regardless of the directive value.





### uwsgi_send_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_send_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `uwsgi_send_timeout 60s;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                              |

Sets a timeout for transmitting a request to the uwsgi server. The timeout is set only between two successive write operations, not for the transmission of the whole request. If the uwsgi server does not receive anything within this time, the connection is closed.





### uwsgi_socket_keepalive

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_socket_keepalive` `on` | `off`;   |
|------------------------------------------------------------------------------------------|------------------------------------------|
| Default                                                                                  | `uwsgi_socket_keepalive off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                   |

Configures the "TCP keepalive" behavior for outgoing connections to a uwsgi server.

| `off`   | By default, the operating system's settings are in effect for the socket.   |
|---------|-----------------------------------------------------------------------------|
| `on`    | The SO_KEEPALIVE socket option is turned on for the socket.                 |





### uwsgi_ssl_certificate

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_ssl_certificate` file;   |
|------------------------------------------------------------------------------------------|---------------------------------|
| Default                                                                                  | —                               |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location          |

Specifies a file with the certificate in the PEM format used for authentication to a secured uwsgi server. The file name can contain variables.





### uwsgi_ssl_certificate_cache

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_ssl_certificate_cache` `off`;

`uwsgi_ssl_certificate_cache` `max=`N [`inactive=`time] [`valid=`time];   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `uwsgi_ssl_certificate_cache off;`                                                                                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                  |

Defines a cache that stores [SSL certificates](#uwsgi-ssl-certificate) and [secret keys](#uwsgi-ssl-certificate-key) specified using variables.

The directive supports the following parameters:

- `max` — sets the maximum number of elements in the cache. When the cache
  overflows, the least recently used (LRU) elements are removed.
- `inactive` — defines the time after which an element is removed if it
  has not been accessed during this time, even if still within its
  `valid` period; each access resets this timer. The default is 10
  seconds.
- `valid` — defines the time during which a cached element is considered
  valid and can be reused. The default is 60 seconds. After this period,
  certificates are reloaded or revalidated.
- `off` — disables the cache.

Example:

```nginx
uwsgi_ssl_certificate       $uwsgi_ssl_server_name.crt;
uwsgi_ssl_certificate_key   $uwsgi_ssl_server_name.key;
uwsgi_ssl_certificate_cache max=1000 inactive=20s valid=1m;
```





### uwsgi_ssl_certificate_key

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_ssl_certificate_key` file;   |
|------------------------------------------------------------------------------------------|-------------------------------------|
| Default                                                                                  | —                                   |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location              |

Specifies a file with the secret key in the PEM format used for authentication to a secured uwsgi server.

The value `engine:`name`:id` can be specified instead of the file, which loads a secret key with a specified id from the OpenSSL engine name.

The value `store:scheme:id` can be specified instead of the file, which is used to load a secret key with a specified id and OpenSSL provider registered URI scheme, such as [pkcs11](https://datatracker.ietf.org/doc/html/rfc7512).

The file name can contain variables.





### uwsgi_ssl_ciphers

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_ssl_ciphers` ciphers;   |
|------------------------------------------------------------------------------------------|--------------------------------|
| Default                                                                                  | `uwsgi_ssl_ciphers DEFAULT;`   |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location         |

Specifies the enabled ciphers for requests to a secured uwsgi server. The ciphers are specified in the format understood by the OpenSSL library.

The list of ciphers depends on the version of OpenSSL installed.
The full list can be viewed using the `openssl ciphers` command.

#### WARNING
The `uwsgi_ssl_ciphers` directive does *not* configure ciphers for TLS
1.3 when using OpenSSL. To tune TLS 1.3 ciphers with OpenSSL, use the
[uwsgi_ssl_conf_command](#uwsgi-ssl-conf-command) directive, which was added to support advanced
SSL configuration.

- In LibreSSL, TLS 1.3 ciphers *can* be configured using
  `uwsgi_ssl_ciphers`.
- In BoringSSL, TLS 1.3 ciphers cannot be configured at all.





### uwsgi_ssl_conf_command

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_ssl_conf_command` name value;   |
|------------------------------------------------------------------------------------------|----------------------------------------|
| Default                                                                                  | —                                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                 |

Sets arbitrary OpenSSL configuration [commands](https://docs.openssl.org/master/man3/SSL_CONF_cmd/) when establishing a connection with a secured uwsgi server.

#### NOTE
The directive is supported when using OpenSSL 1.0.2 or higher.
To configure TLS 1.3 ciphers in OpenSSL, use the `ciphersuites` command.

Multiple uwsgi_ssl_conf_command directives can be specified on the same level. These directives are inherited from the previous configuration level if and only if there are no uwsgi_ssl_conf_command directives defined on the current level.

#### WARNING
Note that reconfiguring OpenSSL directly might result in unexpected behavior.





### uwsgi_ssl_crl

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_ssl_crl` file;   |
|------------------------------------------------------------------------------------------|-------------------------|
| Default                                                                                  | —                       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location  |

Specifies a file with revoked certificates (CRL) in the PEM format used to [verify](#uwsgi-ssl-verify) the certificate of the secured uwsgi server.





### uwsgi_ssl_name

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_ssl_name` name;                         |
|------------------------------------------------------------------------------------------|------------------------------------------------|
| Default                                                                                  | `uwsgi_ssl_name `host name from uwsgi_pass`;\` |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                         |

Allows overriding the server name used to [verify](#uwsgi-ssl-verify) the certificate of the secured uwsgi server and to be [passed through SNI](#uwsgi-ssl-server-name) when establishing a connection with the secured uwsgi server.

The server name can also be specified with variables.

By default, the host name from the [uwsgi_pass](#uwsgi-pass) directive is used.





### uwsgi_ssl_password_file

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_ssl_password_file` file;   |
|------------------------------------------------------------------------------------------|-----------------------------------|
| Default                                                                                  | —                                 |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location            |

Specifies a file with passphrases for [secret keys](#uwsgi-ssl-certificate-key) where each passphrase is specified on a separate line. Passphrases are tried in turn when loading the key.





### uwsgi_ssl_protocols

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_ssl_protocols` [`SSLv2`] [`SSLv3`] [`TLSv1`] [`TLSv1.1`] [`TLSv1.2`] [`TLSv1.3`];   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|
| Default                                                                                  | `uwsgi_ssl_protocols TLSv1.2 TLSv1.3;`                                                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                     |

Enables the specified protocols for requests to a secured uwsgi server.





### uwsgi_ssl_server_name

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_ssl_server_name` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| Default                                                                                  | `uwsgi_ssl_server_name off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                  |

Enables or disables passing the server name
set by the [uwsgi_ssl_name](#uwsgi-ssl-name) directive
via the
[Server Name Indication](http://en.wikipedia.org/wiki/Server_Name_Indication)
TLS extension
(SNI,
[RFC 6066](https://datatracker.ietf.org/doc/html/rfc6066.html))
while establishing a connection with the secured uwsgi server.





### uwsgi_ssl_session_reuse

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_ssl_session_reuse` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-------------------------------------------|
| Default                                                                                  | `uwsgi_ssl_session_reuse on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                    |

Determines whether SSL sessions can be reused when working with the secured uwsgi server. If the errors "SSL3_GET_FINISHED:digest check failed" appear in the logs, try disabling session reuse.





### uwsgi_ssl_trusted_certificate

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_ssl_trusted_certificate` file;   |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| Default                                                                                  | —                                       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                  |

Specifies a file with trusted CA certificates in the PEM format used to [verify](#uwsgi-ssl-verify) the certificate of the uwsgi HTTPS server.





### uwsgi_ssl_verify

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_ssl_verify` `on` | `off`;   |
|------------------------------------------------------------------------------------------|------------------------------------|
| Default                                                                                  | `uwsgi_ssl_verify off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location             |

Enables or disables verification of the uwsgi server certificate.





### uwsgi_ssl_verify_depth

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_ssl_verify_depth` number;   |
|------------------------------------------------------------------------------------------|------------------------------------|
| Default                                                                                  | `uwsgi_ssl_verify_depth 1;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location             |

Sets the verification depth in the uwsgi server certificates chain.





### uwsgi_store

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_store` `on` | `off` | string;   |
|------------------------------------------------------------------------------------------|----------------------------------------|
| Default                                                                                  | `uwsgi_store off;`                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                 |

Enables saving of files to a disk.

| `on`   | saves files with paths corresponding to the directives [alias](https://en.angie.software//angie/docs/configuration/modules/http/index.md#alias) or [root](https://en.angie.software//angie/docs/configuration/modules/http/index.md#root)   |
|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off`  | disables saving of files                                                                                                                                                                                                                    |

The file name can be set explicitly using the string with variables:

```nginx
uwsgi_store /data/www$original_uri;
```

The modification time of files is set according to the received `Last-Modified` response header field. The response is first written to a temporary file, and then the file is renamed. Temporary files and the persistent store can be put on different file systems. However, be aware that in this case a file is copied across two file systems instead of the cheap renaming operation. It is thus recommended that for any given location both saved files and a directory holding temporary files, set by the [uwsgi_temp_path](#uwsgi-temp-path) directive, are put on the same file system.

This directive can be used to create local copies of static unchangeable files, e.g.:

```nginx
location /images/ {
    root               /data/www;
    error_page         404 = /fetch$uri;
}

location /fetch/ {
    internal;

    uwsgi_pass         backend:9000;
    ...

    uwsgi_store        on;
    uwsgi_store_access user:rw group:rw all:r;
    uwsgi_temp_path    /data/temp;

    alias              /data/www/;
}
```





### uwsgi_store_access

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_store_access` users:permissions ...;   |
|------------------------------------------------------------------------------------------|-----------------------------------------------|
| Default                                                                                  | `uwsgi_store_access user:rw;`                 |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                        |

Sets access permissions for newly created files and directories, e.g.:

```nginx
uwsgi_store_access user:rw group:rw all:r;
```

If any `group` or `all` access permissions are specified then user
permissions may be omitted:

```nginx
uwsgi_store_access group:rw all:r;
```





### uwsgi_temp_file_write_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_temp_file_write_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `uwsgi_temp_file_write_size 8k|16k;`                                                                                        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                      |

Limits the size of data written to a temporary file at a time, when buffering of responses from the uwsgi server to temporary files is enabled. By default, size is limited by two buffers set by the [uwsgi_buffer_size](#uwsgi-buffer-size) and [uwsgi_buffers](#uwsgi-buffers) directives. The maximum size of a temporary file is set by the [uwsgi_max_temp_file_size](#uwsgi-max-temp-file-size) directive.





### uwsgi_temp_path

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uwsgi_temp_path` path [level1 [level2 [level3]]]\`;                                                                                                                            |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `uwsgi_temp_path uwsgi_temp;`
(the path depends on the [build parameter](https://en.angie.software//angie/docs/installation/sourcebuild.md#paths) `--http-uwsgi-temp-path`) |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                                                                          |

Defines a directory for storing temporary files with data received from uwsgi servers. Up to three-level subdirectory hierarchy can be used underneath the specified directory. For example, in the following configuration

```nginx
uwsgi_temp_path /spool/angie/uwsgi_temp 1 2;
```

a temporary file might look like this:

```nginx
/spool/angie/uwsgi_temp/7/45/00000123457
```

See also the use_temp_path parameter of the [uwsgi_cache_path](#uwsgi-cache-path) directive.


# https://en.angie.software/angie/docs/configuration/modules/http/http_v2.md





# HTTP/2

Provides support for [HTTP/2](https://datatracker.ietf.org/doc/html/rfc9113).

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module isn't built
by default; it must be enabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--with-http_v2_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
server {
    listen 443 ssl;

    http2 on;

    ssl_certificate server.crt;
    ssl_certificate_key server.key;
}
```

#### NOTE
Note that accepting HTTP/2 connections over TLS requires the "Application-Layer Protocol Negotiation" (ALPN) TLS extension support, which is available since [OpenSSL](http://www.openssl.org/) version 1.0.2.

If the [ssl_prefer_server_ciphers](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-prefer-server-ciphers) directive is set to the value "on", the [ciphers](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-ciphers) should be configured to comply with the [RFC 9113, Appendix A](https://datatracker.ietf.org/doc/html/rfc9113#appendix-A) blacklist and be supported by clients.



## Directives





### http2

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `http2` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-------------------------|
| Default                                                                                  | `http2 off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server            |

Enables the [HTTP/2](https://datatracker.ietf.org/doc/html/rfc9113) protocol.





### http2_body_preread_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `http2_body_preread_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | —                                                                                                                        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                                                                                                             |

Sets the size of the buffer per each request in which the request body may be saved before it is started to be processed.





### http2_chunk_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `http2_chunk_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `http2_chunk_size 8k;`                                                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                            |

Sets the maximum size of chunks into which the response body is sliced. A too low value results in higher overhead. A too high value impairs prioritization due to [head-of-line blocking](http://en.wikipedia.org/wiki/Head-of-line_blocking).





### http2_max_concurrent_pushes

#### Deprecated
Deprecated since version 1.2.0.

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `http2_max_concurrent_pushes` number;   |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| Default                                                                                  | `http2_max_concurrent_pushes 10;`       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                            |

Limits the maximum number of concurrent [push](#http2-push) requests in a connection.





### http2_max_concurrent_streams

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `http2_max_concurrent_streams` number;   |
|------------------------------------------------------------------------------------------|------------------------------------------|
| Default                                                                                  | `http2_max_concurrent_streams 128;`      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                             |

Sets the maximum number of concurrent HTTP/2 streams in a connection.





### http2_push

#### Deprecated
Deprecated since version 1.2.0.

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `http2_push` uri | `off`;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| Default                                                                                  | `http2_push off;`           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location      |

Preemptively sends ([pushes](https://datatracker.ietf.org/doc/html/rfc9113#name-server-push)) a request to the specified uri along with the response to the original request. Only relative URIs with absolute path will be processed, for example:

```nginx
http2_push /static/css/main.css;
```

The `uri` value can contain [variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables).

Several http2_push directives can be specified on the same configuration level. The `off` parameter cancels the effect of the http2_push directives inherited from the previous configuration level.





### http2_push_preload

#### Deprecated
Deprecated since version 1.2.0.

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `http2_push_preload` `on` | `off`;   |
|------------------------------------------------------------------------------------------|--------------------------------------|
| Default                                                                                  | `http2_push_preload off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location               |

Enables automatic conversion of [preload links](https://www.w3.org/TR/preload/#server-push-http-2) specified in the "Link" response header fields into [push](https://datatracker.ietf.org/doc/html/rfc9113#name-server-push) requests.





### http2_recv_buffer_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `http2_recv_buffer_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `http2_recv_buffer_size 256k;`                                                                                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                                                                                                                    |

Sets the size of the per [worker](https://en.angie.software//angie/docs/configuration/modules/core.md#worker-processes) input buffer.



## Built-in Variables

The http_v2 module supports the following built-in variables:



### `$http2`

negotiated protocol identifier:

| `h2`   | for HTTP/2 over TLS           |
|--------|-------------------------------|
| `h2c`  | for HTTP/2 over cleartext TCP |
| `""`   | an empty string otherwise     |


# https://en.angie.software/angie/docs/configuration/modules/http/http_v3.md





# HTTP/3

Provides [HTTP/3](https://datatracker.ietf.org/doc/html/rfc9114)
protocol support for client connections,
as well as for connections with proxied servers
configured using the following
[Proxy](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy) module
directives:

- [proxy_http3_hq](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http3-hq)
- [proxy_http3_max_concurrent_streams](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http3-max-concurrent-streams)
- [proxy_http3_max_table_capacity](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http3-max-table-capacity)
- [proxy_http3_stream_buffer_size](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http3-stream-buffer-size)
- [proxy_http_version](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http-version)
- [proxy_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass)
- [proxy_quic_active_connection_id_limit](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-quic-active-connection-id-limit)
- [proxy_quic_gso](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-quic-gso)
- [proxy_quic_host_key](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-quic-host-key)

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module isn't built
by default; it must be enabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--with-http_v3_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
http {
    log_format quic '$remote_addr - $remote_user [$time_local] '
                    '"$request" $status $body_bytes_sent '
                    '"$http_referer" "$http_user_agent" "$http3"';

    access_log logs/access.log quic;

    server {
        # for better compatibility it's recommended
        # to use the same port for http/3 and https
        listen 8443 quic reuseport;
        listen 8443 ssl;

        ssl_certificate     certs/example.com.crt;
        ssl_certificate_key certs/example.com.key;

        location / {
            # used to advertise the availability of HTTP/3
            add_header Alt-Svc 'h3=":8443"; ma=86400';
        }
    }
}
```

#### NOTE
Note that accepting HTTP/3 connections over TLS requires the TLSv1.3 protocol support, which is available since [OpenSSL](http://www.openssl.org/) version 1.1.1.

0-RTT support requires OpenSSL 3.5.1 or higher. Alternatively, [BoringSSL](https://boringssl.googlesource.com/boringssl/), [LibreSSL](https://www.libressl.org), or [QuicTLS](https://github.com/quictls/openssl) can be used to build and run this module.

Before version 1.29.1, 0-RTT support could not be enabled with OpenSSL regardless of the [ssl_early_data](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-early-data) directive value.

For HTTP/3 requests, if the `Host` header is not passed, the `$http_host` variable is initialized from the `:authority` pseudo-header.

Also, the `reuseport` option can only be specified in one of the `listen ... quic` directives on a server. All other `listen ... quic` directives must be specified without it.



## Directives





### http3

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `http3` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-------------------------|
| Default                                                                                  | `http3 on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server            |

Enables HTTP/3 protocol negotiation.





### http3_hq

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `http3_hq` `on` | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------|
| Default                                                                                  | `http3_hq off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server               |

Enables HTTP/0.9 protocol negotiation used in [QUIC interoperability tests](https://github.com/marten-seemann/quic-interop-runner).

#### WARNING
Enable this mode only to run specialized tests that explicitly require it.





### http3_max_concurrent_streams

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `http3_max_concurrent_streams` number;   |
|------------------------------------------------------------------------------------------|------------------------------------------|
| Default                                                                                  | `http3_max_concurrent_streams 128;`      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                             |

Initializes HTTP/3 and QUIC settings
and sets the maximum number of concurrent HTTP/3 request streams in a connection.





### http3_max_table_capacity

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `http3_max_table_capacity` number;   |
|------------------------------------------------------------------------------------------|--------------------------------------|
| Default                                                                                  | `http3_max_table_capacity 4096;`     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                         |

Sets the [dynamic table](https://www.ietf.org/archive/id/draft-ietf-quic-qpack-20.html#name-dynamic-table)
capacity for server connections.

#### NOTE
A similar [proxy_http3_max_table_capacity](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http3-max-table-capacity) directive
does this for proxy connections.
To avoid errors,
dynamic table usage is disabled when proxying with caching is enabled.





### http3_stream_buffer_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `http3_stream_buffer_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `http3_stream_buffer_size 64k;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                                                                                                              |

Sets the [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units) of the buffer used for reading and writing of the QUIC streams.





### quic_active_connection_id_limit

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `quic_active_connection_id_limit` number;   |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| Default                                                                                  | `quic_active_connection_id_limit 2;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                                |

Sets the QUIC active_connection_id_limit transport parameter value. This is the maximum number of connection IDs that can be stored on the server.





### quic_bpf

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `quic_bpf` `on` | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------|
| Default                                                                                  | `quic_bpf off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | main                       |

Enables routing of QUIC packets using [eBPF](https://ebpf.io/). When enabled, this allows supporting QUIC connection migration.

#### NOTE
The directive is only supported on Linux 5.7+.





### quic_gso

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `quic_gso` `on` | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------|
| Default                                                                                  | `quic_gso off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server               |

Enables sending in optimized batch mode using segmentation offloading.

#### NOTE
Optimized sending is supported only on Linux featuring `UDP_SEGMENT`.





### quic_host_key

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `quic_host_key` file;   |
|------------------------------------------------------------------------------------------|-------------------------|
| Default                                                                                  | —                       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server            |

Sets a file with the secret key used to encrypt stateless reset and address validation tokens. By default, a random key is generated on each reload. Tokens generated with old keys are not accepted.





### quic_retry

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `quic_retry` `on` | `off`;   |
|------------------------------------------------------------------------------------------|------------------------------|
| Default                                                                                  | `quic_retry off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                 |

Enables the [QUIC Address Validation](https://datatracker.ietf.org/doc/html/rfc9000#name-address-validation) feature. This includes sending a new token in a Retry packet or a NEW_TOKEN frame and validating a token received in the Initial packet.



## Built-in Variables

The http_v3 module supports the following built-in variables:



### `$http3`

negotiated protocol identifier:

| `h3`   | for HTTP/3 connections    |
|--------|---------------------------|
| `hq`   | for hq connections        |
| `""`   | an empty string otherwise |



### `$quic_connection`

QUIC connection serial number


# https://en.angie.software/angie/docs/configuration/modules/http/http_xslt.md





# XSLT

The module is a filter that transforms XML responses using one or more XSLT stylesheets.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module isn't built
by default; it must be enabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--with-http_xslt_module`.

In [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the module is built
[dynamically](https://en.angie.software//angie/docs/installation/index.md#install-dynamicmodules) and is available as a separate
package named `angie-module-xslt` or `angie-pro-module-xslt`.

In our repositories, the module is built
[dynamically](https://en.angie.software//angie/docs/installation/index.md#install-dynamicmodules)
and is available as a separate package named `angie-module-xslt` or `angie-pro-module-xslt`.

#### NOTE
This module requires the [libxml2](http://xmlsoft.org/) and [libxslt](http://xmlsoft.org/XSLT/) libraries.



## Configuration Example

```nginx
location / {
    xml_entities    /site/dtd/entities.dtd;
    xslt_stylesheet /site/xslt/one.xslt param=value;
    xslt_stylesheet /site/xslt/two.xslt;
}
```



## Directives





### xml_entities

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `xml_entities` path;   |
|------------------------------------------------------------------------------------------|------------------------|
| Default                                                                                  | —                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location |

Specifies the DTD file that declares character entities. This file is compiled at the configuration stage. For technical reasons, the module is unable to use the external subset declared in the processed XML, so it is ignored and a specially defined file is used instead. This file should not describe the XML structure. It is enough to declare just the required character entities, for example:

```xml

```





### xslt_last_modified

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `xslt_last_modified` `on` | `off`;   |
|------------------------------------------------------------------------------------------|--------------------------------------|
| Default                                                                                  | `xslt_last_modified off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location               |

Allows preserving the `Last-Modified` header field from the original response during XSLT transformations to facilitate response caching.

By default, the header field is removed as contents of the response are modified during transformations and may contain dynamically generated elements or parts that are changed independently of the original response.





### xslt_param

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `xslt_param` parameter value;   |
|------------------------------------------------------------------------------------------|---------------------------------|
| Default                                                                                  | —                               |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location          |

Defines the parameters for XSLT stylesheets. The value is treated as an XPath expression. The value can contain [variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables). To pass a string value to a stylesheet, the [xslt_string_param](#xslt-string-param) directive can be used.

There could be several `xslt_param` directives. These directives are inherited from the previous configuration level if and only if there are no `xslt_param` and [xslt_string_param](#xslt-string-param) directives defined on the current level.





### xslt_string_param

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `xslt_string_param` parameter value;   |
|------------------------------------------------------------------------------------------|----------------------------------------|
| Default                                                                                  | —                                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                 |

Defines the string parameters for XSLT stylesheets. XPath expressions in the value are not interpreted. The value can contain variables.

There could be several `xslt_string_param` directives. These directives are inherited from the previous configuration level if and only if there are no [xslt_param](#xslt-param) and `xslt_string_param` directives defined on the current level.





### xslt_stylesheet

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `xslt_stylesheet` stylesheet [parameter=value ...];   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------|
| Default                                                                                  | —                                                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | location                                              |

Defines the XSLT stylesheet and its optional parameters. A stylesheet is compiled at the configuration stage.

Parameters can either be specified separately, or grouped in a single line using the ":" delimiter. If a parameter includes the ":" character, it should be escaped as "%3A". Also, libxslt requires to enclose parameters that contain non-alphanumeric characters into single or double quotes, for example:

```console
param1='http%3A//www.example.com':param2=value2
```

The parameters description can contain variables, for example, the whole line of parameters can be taken from a single variable:

```nginx
location / {
    xslt_stylesheet /site/xslt/one.xslt
                    $arg_xslt_params
                    param1='$value1':param2=value2
                    param3=value3;
}
```

It is possible to specify several stylesheets. They will be applied sequentially in the specified order.





### xslt_types

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `xslt_types` mime-type ...;   |
|------------------------------------------------------------------------------------------|-------------------------------|
| Default                                                                                  | `xslt_types text/xml;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location        |

Enables transformations in responses with the specified MIME types in addition to `text/xml`. The special value "\*" matches any MIME type. If the transformation result is an HTML response, its MIME type is changed to `text/html`.


# https://en.angie.software/angie/docs/configuration/modules/stream.md






# Stream Module

The core stream module implements basic functionality for handling TCP and UDP
connections: this includes defining server blocks, traffic routing, configuring
proxying, SSL/TLS support, and managing connections for streaming services, such
as databases, DNS, and other protocols that operate over TCP and UDP.

The other modules in this section extend this functionality, allowing you to
flexibly configure and optimize the stream server for various scenarios and
requirements.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module isn't built
by default; it must be enabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--with-stream`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
worker_processes auto;

error_log /var/log/angie/error.log info;

events {
    worker_connections  1024;
}

stream {
    upstream backend {
        hash $remote_addr consistent;

        server backend1.example.com:12345 weight=5;
        server 127.0.0.1:12345            max_fails=3 fail_timeout=30s;
        server unix:/tmp/backend3;
    }

    upstream dns {
       server 192.168.0.1:53535;
       server dns.example.com:53;
    }

    server {
        listen 12345;
        proxy_connect_timeout 1s;
        proxy_timeout 3s;
        proxy_pass backend;
    }

    server {
        listen 127.0.0.1:53 udp reuseport;
        proxy_timeout 20s;
        proxy_pass dns;
    }

    server {
        listen [::1]:12345;
        proxy_pass unix:/tmp/stream.socket;
    }
}
```



## Directives





### error_log_user_tag

#### Versionadded
Added in version 1.12.0.

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `error_log_user_tag` value;   |
|------------------------------------------------------------------------------------------|-------------------------------|
| Default                                                                                  | —                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                |

Adds a session-specific tag to [error_log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log) records. The value can
[contain variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables). The directive can be specified
multiple times to add multiple tags. Tags can be matched with
`filter=tag:` in [error_log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log).





### listen

#### Versionchanged
Changed in version 1.10.0.

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `listen` address[:port] [`ssl`] [`udp`] [`proxy_protocol`] [`setfib=`number] [`fastopen=`number] [`backlog=`number] [`rcvbuf=`size] [`sndbuf=`size] [`accept_filter=`filter] [`deferred`] [`bind`] [`ipv6only=``on` | `off`] [`reuseport`] [`so_keepalive=`on|off|[`keepidle`]:[`keepintvl`]:[`keepcnt`]];   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | —                                                                                                                                                                                                                                                                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | server                                                                                                                                                                                                                                                                                                       |

Sets the address and port for the socket on which the server will accept connections. It is possible to specify just the port, so Angie listens on all available IPv4 (and IPv6, if enabled) interfaces. The address can also be a hostname, for example:

```nginx
listen 127.0.0.1:12345;
listen *:12345;
listen 12345;     # same as *:12345
listen localhost:12345;
```

IPv6 addresses are specified in square brackets:

```nginx
listen [::1]:12345;
listen [::]:12345;
```

Port ranges are specified with the first and last port separated by a hyphen:

```nginx
listen 127.0.0.1:12345-12399;
listen 12345-12399;
```

UNIX domain sockets are specified with the `unix:` prefix:

```nginx
listen unix:/var/run/angie.sock;
```

#### NOTE
Different servers must listen on different address:port pairs.

| `ssl`            | allows specifying that all connections accepted on this port should work in SSL mode.                                                                                                      |
|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `udp`            | configures a listening socket for working with datagrams. In order to handle packets from the same address and port in the same session, the reuseport parameter should also be specified. |
| `proxy_protocol` | allows specifying that all connections accepted on this port should use the PROXY protocol.                                                                                                |

The `listen` directive can have several additional parameters specific to socket-related system calls.

| `setfib=`number        | sets the associated routing table, FIB (the `SO_SETFIB` option) for
the listening socket. This currently works only on FreeBSD.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
|------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `fastopen=`number      | enables "TCP Fast Open" for the listening socket and [limits](https://datatracker.ietf.org/doc/html/rfc7413#section-5.1) the maximum length for the queue of connections that have not yet completed the three-way handshake.

#### WARNING
Do not enable this feature unless the server can handle receiving the [same SYN packet with data](https://datatracker.ietf.org/doc/html/rfc7413#section-6.1) more than once.                                                                                                                                                                                                                                                                                                                        |
| `backlog=`number       | sets the `backlog` parameter in the `listen()` call that
limits the maximum length for the queue of pending connections. By
default, `backlog` is set to `-1` on FreeBSD, DragonFly BSD,
and macOS, and to 511 on other platforms.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `rcvbuf=`size          | sets the receive buffer size (the `SO_RCVBUF` option) for the listening socket.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `sndbuf=`size          | sets the send buffer size (the `SO_SNDBUF` option) for the listening socket.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `accept_filter=`filter | sets the name of accept filter (the `SO_ACCEPTFILTER` option) for
the listening socket that filters incoming connections before passing
them to `accept()`. This works only on FreeBSD and NetBSD 5.0+.
Acceptable values are `dataready` and `httpready`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `deferred`             | instructs to use a deferred `accept()` (the
`TCP_DEFER_ACCEPT` socket option) on Linux.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `bind`                 | this parameter instructs to make a separate `bind()` call for a
given address:port pair. The fact is that if there are several
`listen` directives with the same port but different addresses,
and one of the `listen` directives listens on all addresses for the
given port (\*:port), Angie will `bind()` only to \*:port. It should be
noted that the `getsockname()` system call will be made in this case to
determine the address that accepted the connection. If the `setfib`,
`fastopen`, `backlog`, `rcvbuf`, `sndbuf`,
`accept_filter`, `deferred`, `ipv6only`,
`reuseport`, or `so_keepalive` parameters are used then for a
given address:port pair a separate `bind()` call will always be
made. |
| `ipv6only=on` | `off`  | this parameter determines (via the `IPV6_V6ONLY` socket option)
whether an IPv6 socket listening on a wildcard address [::] will accept
only IPv6 connections or both IPv6 and IPv4 connections. This parameter
is turned on by default. It can only be set once on start.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `reuseport`            | this parameter instructs to create an individual listening socket for
each worker process (using the `SO_REUSEPORT` socket option on
Linux 3.9+ and DragonFly BSD, or `SO_REUSEPORT_LB` on FreeBSD 12+),
allowing a kernel to distribute incoming connections between worker
processes. This currently works only on Linux 3.9+, DragonFly BSD, and
FreeBSD 12+.

#### WARNING
Inappropriate use of this option may have its security implications.                                                                                                                                                                                                                                                                         |
| `multipath`            | enables accepting connections via [Multipath TCP](https://en.wikipedia.org/wiki/Multipath_TCP) (MPTCP) protocol,
supported in Linux kernel starting from version 5.6.
This parameter is **incompatible** with `udp`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

`so_keepalive=on` | `off` | [`keepidle`]:[`keepintvl`]:[`keepcnt`]

Configures the "TCP keepalive" behavior for the listening socket.

| `''`   | if this parameter is omitted then the operating system's settings will be in effect for the socket   |
|--------|------------------------------------------------------------------------------------------------------|
| `on`   | the SO_KEEPALIVE option is turned on for the socket                                                  |
| `off`  | the SO_KEEPALIVE option is turned off for the socket                                                 |

Some operating systems support setting of TCP keepalive parameters on a
per-socket basis using the `TCP_KEEPIDLE`, `TCP_KEEPINTVL`, and
`TCP_KEEPCNT` socket options. On such systems (currently, Linux 2.4+,
NetBSD 5+, and FreeBSD 9.0-STABLE), they can be configured using the keepidle,
keepintvl, and keepcnt parameters. One or two parameters may be omitted, in
which case the system default setting for the corresponding socket option will
be in effect.

For example,

```nginx
so_keepalive=30m::10
```

will set the idle timeout (`TCP_KEEPIDLE`) to 30 minutes, leave the probe interval (`TCP_KEEPINTVL`) at its system default, and set the probes count (`TCP_KEEPCNT`) to 10 probes.





### preread_buffer_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `preread_buffer_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `preread_buffer_size 16k;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                                                                                                       |

Specifies a size of the [preread](https://en.angie.software//angie/docs/configuration/processing.md#stream-sessions) buffer.





### preread_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `preread_timeout` timeout;   |
|------------------------------------------------------------------------------------------|------------------------------|
| Default                                                                                  | `preread_timeout 30s;`       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server               |

Specifies a timeout of the [preread](https://en.angie.software//angie/docs/configuration/processing.md#stream-sessions) phase.





### proxy_protocol_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_protocol_timeout` timeout;   |
|------------------------------------------------------------------------------------------|-------------------------------------|
| Default                                                                                  | `proxy_protocol_timeout 30s;`       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                      |

Specifies a timeout for reading the PROXY protocol header to complete. If the entire header is not transmitted within this time, the connection is closed.





### resolver

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `resolver` [address ...] [`conf` [`=`file]] [`valid=`time] [`ipv4=``on` | `off`] [`ipv6=``on` | `off`] [`status_zone=`zone];

`resolver` `off`;   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `resolver conf;`                                                                                                                                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server, upstream                                                                                                                                  |

Configures name servers used to resolve names of upstream servers into addresses, for example:

```nginx
resolver 127.0.0.53 [::1]:5353;
```

The address can be specified as a domain name or IP address, with an optional port. If port is not specified, the port 53 is used. Name servers are queried in a round-robin fashion.

At least one DNS server address or the `conf` parameter must be specified,
except in the `resolver off;` form.

#### NOTE
Prefer a local trusted resolver such as `127.0.0.53` (systemd-resolved)
over a public one (e.g. `8.8.8.8`). Public resolvers expose DNS queries
to third parties and increase susceptibility to cache-poisoning attacks.

#### NOTE
The directive value is inherited by nested blocks
and can be overridden in them if necessary.
Within a single block the directive may be specified only once;
repeating it is a configuration error.

Enables DNS resolution for upstream servers referenced through variables or
configured with the [resolve](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-reresolve) parameter, and for OCSP
stapling.

Besides explicit server addresses, the directive recognizes:

| `off`            | explicitly disables DNS name resolution                                                                    |
|------------------|------------------------------------------------------------------------------------------------------------|
| `conf` [`=`file] | reads DNS server addresses from the specified file, or from
`/etc/resolv.conf` if no file is specified |

The file may contain `nameserver` lines in the same format used by the
system resolver:

```text
nameserver 127.0.1.4
nameserver 127.0.1.5
```

Addresses read from the file are added to any addresses specified explicitly
in the directive, and all of them are then queried together in a
round-robin fashion. If the file is absent, cannot be read, or lists no
addresses, and none are configured explicitly, Angie falls back to the
default server `127.0.0.1:53`.

At runtime, Angie re-reads the file when it changes, updating the set of DNS
servers.

By default, Angie caches each answer for the duration of the TTL value in the
DNS response. The optional `valid` parameter overrides this:

| `valid`   | *optional* parameter allows overriding the response cache validity   |
|-----------|----------------------------------------------------------------------|
```nginx
resolver 127.0.0.53 [::1]:5353 valid=30s;
```

By default, Angie will look up both IPv4 and IPv6 addresses while resolving.

| `ipv4=off`   | disables looking up of IPv4 addresses   |
|--------------|-----------------------------------------|
| `ipv6=off`   | disables looking up of IPv6 addresses   |



| `status_zone`   | *optional* parameter;
enables the collection of DNS server request and response metrics
([/status/resolvers/](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-resolvers))
in the specified zone   |
|-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|





### resolver_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `resolver_timeout` time;   |
|------------------------------------------------------------------------------------------|----------------------------|
| Default                                                                                  | `resolver_timeout 30s;`    |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server, upstream   |

Sets a timeout for name resolution, for example:

```nginx
```

resolver_timeout 5s;





### server

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `server` { ... }   |
|------------------------------------------------------------------------------------------|--------------------|
| Default                                                                                  | —                  |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream             |

Sets the configuration for a server.





### server_name

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `server_name` name ...;   |
|------------------------------------------------------------------------------------------|---------------------------|
| Default                                                                                  | `server_name "";`         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | server                    |

Sets names of a virtual server.

#### WARNING
In the `stream` module, the `server_name` directive is based on Server Name
Indication ([SNI](https://en.angie.software//angie/docs/configuration/ssl.md#sni)) and only works with TLS connections. To use it,
you must [configure TLS termination](https://en.angie.software//angie/docs/configuration/ssl.md#ssl-config) or [enable TLS
preread](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl_preread.md#stream-ssl-preread) in the corresponding `server` block.

Example configuration:

```nginx
server {
    listen 443 ssl;
    server_name example.com www.example.com;
    ssl_certificate /etc/angie/cert.pem;
    ssl_certificate_key /etc/angie/key.pem;
}
```

The first name becomes the primary server name.

Server names can include an asterisk (`*`)
to replace the first or last part of a name:

```nginx
server {
    server_name example.com *.example.com www.example.*;
}
```

These names are called wildcard names.

You can also use regular expressions in server names by preceding the name with
a tilde (`~`):

```none
server {
    server_name www.example.com ~^www\d+\.example\.com$;
}
```

Regular expressions may include captures that can be used in other directives:

```nginx
server {
    server_name ~^(www\.)?(.+)$;

    proxy_pass www.$2:12345;
}
```

Named captures in regular expressions create variables
that can be used in other directives:

```nginx
server {
    server_name ~^(www\.)?(?.+)$;

    proxy_pass www.$domain:12345;
}
```

If the directive's parameter is set to `$hostname`, the machine's hostname
is inserted.

When searching for a virtual server by name, if the name matches more than one
of the specified variants (e.g., both a wildcard name and a regular expression
match), the first matching variant will be chosen in the following order of
priority:

- The exact name
- The longest wildcard name starting with an asterisk, e.g.,
  `*.example.com`
- The longest wildcard name ending with an asterisk, e.g., `mail.*`
- The first matching regular expression (in order of appearance in the
  configuration file)





### server_names_hash_bucket_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `server_names_hash_bucket_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `server_names_hash_bucket_size 32|64|128;`                                                                                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream                                                                                                                         |

Sets the bucket size for the server names hash tables. The default value depends
on the size of the processor's cache line.





### server_names_hash_max_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `server_names_hash_max_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `server_names_hash_max_size 512;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream                                                                                                                      |

Sets the maximum size of the server names hash tables.





### status_zone

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `status_zone` zone | key `zone=`zone[:count];   |
|------------------------------------------------------------------------------------------|-------------------------------------------------|
| Default                                                                                  | —                                               |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | server                                          |

Allocates a shared memory zone to collect metrics for
[/status/stream/server_zones/](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-stream-server-zones).

Multiple `server` contexts can share the same zone for data collection.

The single-value zone syntax aggregates all metrics for the current context
in one shared memory zone:

```nginx
server {

    listen 80;
    server_name *.example.com;

    status_zone single;
    # ...
}
```

The alternative syntax allows specifying the following parameters:

| key              | A string with variables,
whose value determines the grouping of connections in the zone.
All connections producing identical values after substitution
are grouped together.
If substitution yields an empty value, metrics aren't updated.   |
|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| zone             | The name of the shared memory zone.                                                                                                                                                                                                                           |
| count (optional) | The maximum number of separate groups for collecting metrics.
If new key values would exceed this limit,
they are grouped under zone instead.

The default value is 1.                                                                        |

In the following example,
all connections with the same `$server_addr` value
are grouped into `host_zone`.
Metrics are collected separately for each unique `$server_addr`
until the number of metric groups reaches 10.
After that, any new `$server_addr` values
will be added to the `server_zone` group:

```nginx
stream {

    upstream backend {
        server 192.168.0.1:3306;
        server 192.168.0.2:3306;
        # ...
    }

    server {

        listen 3306;
        proxy_pass backend;

        status_zone $server_addr zone=server_zone:10;
    }
}
```

The resulting metrics are split between individual servers in the API output.

#### NOTE
These metrics are collected only when `status_zone` is set. Without it,
the server does not appear in [/status/stream/server_zones/](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-stream-server-zones), the
[TCP/UDP Zones Widget](https://en.angie.software//angie/docs/configuration/monitoring.md#tcp-udp-zones-widget), or [Prometheus](https://en.angie.software//angie/docs/configuration/modules/http/http_prometheus.md#http-prometheus) output, and no warning
is logged.





### stream

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `stream` { ... }   |
|------------------------------------------------------------------------------------------|--------------------|
| Default                                                                                  | —                  |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | main               |

Provides the configuration file context in which the stream server directives are specified.





### tcp_nodelay

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `tcp_nodelay` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-------------------------------|
| Default                                                                                  | `tcp_nodelay on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                |

Enables or disables the use of the `TCP_NODELAY` option. The option is enabled for both client connections and connections to proxied servers.





### time_format

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `time_format` $variable format;   |
|------------------------------------------------------------------------------------------|-----------------------------------|
| Default                                                                                  | —                                 |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream                            |

Defines a $variable to hold the current local time, rendered with a custom
format string of `strftime`-like specifiers plus `%L` for
milliseconds. The directive is useful where [$time_local](#v-s-time-local)
and [$time_iso8601](#v-s-time-iso8601) fall short, for example because they
provide no sub-second precision:

```nginx
time_format $time_ms "%Y-%m-%dT%H:%M:%S.%L%Z";

log_format tf '$time_ms $remote_addr $status';
```

With the format above, `$time_ms` expands to a value such as `2024-01-15T14:34:56.789+03:00`.

Redefining a built-in variable, such as [$time_local](#v-s-time-local), or
repeating `time_format` for the same name fails the configuration load
with an error like: "the duplicate "..." variable".

The format string accepts the following specifiers, evaluated in the same
local time zone as [$time_local](#v-s-time-local):

| `%Y`       | 4-digit year                               |
|------------|--------------------------------------------|
| `%y`       | 2-digit year                               |
| `%m`       | month, `01-12`                             |
| `%d`       | day of month, `01-31`                      |
| `%e`       | day of month, space-padded, `1-31`         |
| `%H`       | hour, `00-23`                              |
| `%I`       | hour, `01-12`                              |
| `%M`       | minute, `00-59`                            |
| `%S`       | second, `00-59`                            |
| `%L`       | milliseconds, `000-999`                    |
| `%p`       | uppercase `AM` / `PM`                      |
| `%P`       | lowercase `am` / `pm`                      |
| `%a`       | abbreviated weekday name, `Sun-Sat`        |
| `%A`       | full weekday name, `Sunday-Saturday`       |
| `%b`, `%h` | abbreviated month name, `Jan-Dec`          |
| `%B`       | full month name, `January-December`        |
| `%z`       | time zone offset, `+0300`                  |
| `%Z`       | time zone offset, ISO 8601 style, `+03:00` |
| `%n`       | newline                                    |
| `%t`       | tab                                        |
| `%%`       | literal `%`                                |

#### NOTE
An unrecognized specifier is copied to the output verbatim, including the
leading `%`; a standalone `%` at the very end of the format
string is dropped.





### variables_hash_bucket_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `variables_hash_bucket_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `variables_hash_bucket_size 64;`                                                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream                                                                                                                      |

Sets the bucket size for the variables hash table. The details of setting up hash tables are provided in a separate [document](https://en.angie.software//angie/docs/configuration/configfile.md#configure-hashes).





### variables_hash_max_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `variables_hash_max_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `variables_hash_max_size 1024;`                                                                                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream                                                                                                                   |

Sets the maximum size of the variables hash table. The details of setting up hash tables are provided in a separate [document](https://en.angie.software//angie/docs/configuration/configfile.md#configure-hashes).



## Built-in Variables

The core stream module supports the following built-in variables:



### `$angie_version`

Angie version



### `$binary_remote_addr`

client address in a binary form, value's length is always 4 bytes for IPv4 addresses or 16 bytes for IPv6 addresses



### `$bytes_received`

number of bytes received from the client



### `$bytes_sent`

number of bytes sent to the client



### `$connection`

connection serial number



### `$hostname`

host name



### `$msec`

current time in seconds with milliseconds resolution



### `$nginx_version`

nginx version



### `$pid`

PID of the worker process



### `$protocol`

protocol used to communicate with the client: `TCP` or `UDP`



### `$proxy_protocol_addr`

client address from the PROXY protocol header.
The PROXY protocol must be previously enabled by setting the proxy_protocol parameter in the [listen](#s-listen) directive.



### `$proxy_protocol_port`

client port from the PROXY protocol header.
The PROXY protocol must be previously enabled by setting the proxy_protocol parameter in the [listen](#s-listen) directive.



### `$proxy_protocol_server_addr`

server address from the PROXY protocol header.
The PROXY protocol must be previously enabled by setting the proxy_protocol parameter in the [listen](#s-listen) directive.



### `$proxy_protocol_server_port`

server port from the PROXY protocol header.
The PROXY protocol must be previously enabled by setting the proxy_protocol parameter in the [listen](#s-listen) directive.



### `$proxy_protocol_tlv_`

TLV obtained from the PROXY protocol header. The name can be a TLV type name or its numeric value. In the latter case, the value is specified in hexadecimal and must start with 0x:

```none
$proxy_protocol_tlv_alpn
$proxy_protocol_tlv_0x01
```

SSL TLVs can also be accessed by both TLV type name and its numeric value, both must start with `ssl_`:

```none
$proxy_protocol_tlv_ssl_version
$proxy_protocol_tlv_ssl_0x21
```

The following TLV type names are supported:

* `alpn (0x01)` - upper layer protocol used over the connection
* `authority (0x02)` - host name value passed by the client
* `unique_id (0x05)` - unique connection identifier
* `netns (0x30)` - namespace name
* `ssl (0x20)` - SSL TLV structure in binary format

The following SSL TLV type names are supported:

* `ssl_version (0x21)` - SSL version used in client connection
* `ssl_cn (0x22)` - certificate Common Name
* `ssl_cipher (0x23)` - name of the used cipher
* `ssl_sig_alg (0x24)` - algorithm used to sign the certificate
* `ssl_key_alg (0x25)` - public key algorithm

Also supported is the following special SSL TLV type name:

* `ssl_verify` - client certificate verification result: 0 if the client presented a certificate and it was successfully verified, or non-zero otherwise

The PROXY protocol must be previously enabled by setting the proxy_protocol parameter in the [listen](#s-listen) directive.



### `$remote_addr`

client address



### `$remote_port`

client port



### `$server_addr`

address of the server which accepted a connection.
Computing a value of this variable usually requires one system call. To avoid a system call, the [listen](#s-listen) directives must specify addresses and use the `bind` parameter.



### `$server_port`

port of the server which accepted a connection



### `$session_time`

session duration in seconds with milliseconds resolution



### `$status`

session status, can be one of the following:

| `200`   | session completed successfully                                                                                                                                                                     |
|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `400`   | client data could not be parsed, for example, the PROXY protocol header                                                                                                                            |
| `403`   | access forbidden, for example, when access is limited for [certain client addresses](https://en.angie.software//angie/docs/configuration/modules/stream/stream_access.md#stream-access)            |
| `500`   | internal server error                                                                                                                                                                              |
| `502`   | bad gateway, for example, if an upstream server could not be selected or reached                                                                                                                   |
| `503`   | service unavailable, for example, when access is limited by the [number of connections](https://en.angie.software//angie/docs/configuration/modules/stream/stream_limit_conn.md#stream-limit-conn) |



### `$time_iso8601`

local time in the ISO 8601 standard format



### `$time_local`

local time in the Common Log Format


# https://en.angie.software/angie/docs/configuration/modules/stream/stream_access.md





# Access

The module allows limiting access to certain client addresses.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by
default together with the [Stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) module (enabled with
`--with-stream`); it can be disabled with the
[build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure) `--without-stream_access_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
server {
    ...
    deny  192.168.1.1;
    allow 192.168.1.0/24;
    allow 10.1.1.0/16;
    allow 2001:0db8::/32;
    deny  all;
}
```

The rules are checked in sequence until the first match is found. In this example, access is allowed only for IPv4 networks `10.1.1.0/16` and `192.168.1.0/24` excluding the address `192.168.1.1`, and for IPv6 network `2001:0db8::/32`.



## Directives





### allow

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `allow` address | CIDR | `unix:` | `all`;   |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| Default                                                                                  | —                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                              |

Allows access for the specified network or address. If the special value `unix:` is specified, allows access for all UNIX domain sockets.





### deny

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `deny` address | CIDR | `unix:` | `all`;   |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| Default                                                                                  | —                                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                             |

Denies access for the specified network or address. If the special value `unix:` is specified, denies access for all UNIX domain sockets.


# https://en.angie.software/angie/docs/configuration/modules/stream/stream_acme.md





# ACME

#### Versionadded
Added in version 1.10.0.

Allows automatic certificate acquisition
using the [ACME](https://datatracker.ietf.org/doc/html/rfc8555) protocol
for servers defined in the `stream` context.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module isn't built
by default; it must be enabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--with-stream_acme_module`
(also requires `--with-http_acme_module`).

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.

#### NOTE
For correct operation, the `stream` block
must be located after the `http` block.
This is because the stream module uses client definitions
created during HTTP configuration parsing.



## Configuration Example

In this example, certificates obtained by the `example` ACME client
(declared in the `http` block) secure a TCP server using the default
HTTP validation:

```nginx
# HTTP part
http {

    resolver 127.0.0.53;

    # ACME client for the stream part
    acme_client example https://acme-v02.api.letsencrypt.org/directory;

    # Server for HTTP validation
    server {

        listen 80;
        return 444;
    }
}

# Stream part
stream {

    server {

        listen 12345 ssl;
        proxy_pass backend_upstream;

        ssl_certificate $acme_cert_example;
        ssl_certificate_key $acme_cert_key_example;

        server_name example.com www.example.com;
        acme example; # reference to the ACME client defined in the HTTP part
    }

    upstream backend_upstream {

        server 127.0.0.1:54321;
    }
}
```

For configuration examples and setup instructions, including DNS validation,
see the [ACME in the Stream Module](https://en.angie.software//angie/docs/configuration/acme.md#acme-config-stream) section.



## Directives





### acme

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `acme` name;   |
|------------------------------------------------------------------------------------------|----------------|
| Default                                                                                  | —              |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | server         |

Specifies the [ACME client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) from the HTTP module that obtains
a certificate for the valid identifiers in this [server](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#s-server) block.
A single certificate covers all valid domain names and IP addresses specified
in [server_name](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#s-server-name) directives of every [server](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#s-server) block that
references the client with the given name;
if the `server_name` configuration changes,
the certificate will be updated to account for the changes.

On each Angie startup or configuration reload, new certificates are requested
for all identifiers that lack a valid certificate.
Possible reasons include certificate expiration,
missing files or inability to read them,
and changes in certificate settings.

#### NOTE
Currently, domains specified via regular expressions
are not supported and will be skipped.

Wildcard domains are supported only in `challenge=dns` mode
in `acme_client`.

IPv4 and IPv6 addresses are supported unless the client uses
`challenge=dns`. With DNS validation enabled, IP addresses are skipped.

This directive can be specified multiple times
to load certificates of different types, for example RSA and ECDSA:

```nginx
server {

    listen 12345 ssl;
    server_name example.com www.example.com;

    ssl_certificate $acme_cert_rsa;
    ssl_certificate_key $acme_cert_key_rsa;

    ssl_certificate $acme_cert_ecdsa;
    ssl_certificate_key $acme_cert_key_ecdsa;

    acme rsa;
    acme ecdsa;
}
```



## Embedded Variables



### `$acme_cert_`

Contents of the last certificate file (if any)
obtained by the client with this name.



### `$acme_cert_key_`

Contents of the certificate key file
used by the client with this name.

#### NOTE
The certificate file is available
only if the ACME client has obtained at least one certificate,
while the key file is available immediately after startup.


# https://en.angie.software/angie/docs/configuration/modules/stream/stream_geo.md





# Geo

The module creates variables with values depending on the client IP address.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by
default together with the [Stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) module (enabled with
`--with-stream`); it can be disabled with the
[build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure) `--without-stream_geo_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
geo $geo {
    default        0;

    127.0.0.1      2;
    192.168.1.0/24 1;
    10.1.0.0/16    1;

    ::1            2;
    2001:0db8::/32 1;
}
```



## Directives





### geo

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `geo` [$address] $variable { ... }   |
|------------------------------------------------------------------------------------------|--------------------------------------|
| Default                                                                                  | —                                    |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream                               |

Describes the dependency of values of the specified variable on the client IP address. By default, the address is taken from the [$remote_addr](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-remote-addr) variable, but it can also be taken from another variable, for example:

```nginx
geo $arg_remote_addr $geo {
    ...;
}
```

#### NOTE
Since variables are evaluated only when used, the mere existence of even a large number of declared `geo` variables does not cause any extra costs for connection processing.

If the value of a variable does not represent a valid IP address then the "255.255.255.255" address is used.

Addresses are specified either as prefixes in CIDR notation (including individual addresses) or as ranges.

The following special parameters are also supported:

| `delete`   | deletes the specified network                                                                                                                                                                                                                                                            |
|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `default`  | the value set to the variable if the client address does not match any of the specified addresses. When addresses are specified in CIDR notation, "`0.0.0.0/0`" and "`:/0`" can be used instead of `default`. When `default` is not specified, the default value will be an empty string |
| `include`  | includes a file with addresses and values. The file name can contain glob wildcards, in which case all matching files are included. There can be several inclusions.                                                                                                                     |
| `ranges`   | indicates that addresses are specified as ranges. This parameter should be the first. To speed up loading of a geo base, addresses should be put in ascending order.                                                                                                                     |
| `volatile` | indicates that the variable is not cacheable.                                                                                                                                                                                                                                            |

Example:

```nginx
geo $country {
    default        ZZ;
    include        conf/geo.conf;
    delete         127.0.0.0/16;

    127.0.0.0/24   US;
    127.0.0.1/32   RU;
    10.1.0.0/16    RU;
    192.168.1.0/24 UK;
}
```

The `conf/geo.conf` file could contain the following lines:

```console
10.2.0.0/16    RU;
192.168.2.0/24 RU;
```

A value of the most specific match is used. For example, for the `127.0.0.1` address the value `RU` will be chosen, not `US`.

Example with ranges:

```nginx
geo $country {
    ranges;
    default                   ZZ;
    127.0.0.0-127.0.0.0       US;
    127.0.0.1-127.0.0.1       RU;
    127.0.0.2-127.0.0.255     US;
    10.1.0.0-10.1.255.255     RU;
    192.168.1.0-192.168.1.255 UK;
}
```


# https://en.angie.software/angie/docs/configuration/modules/stream/stream_geoip.md





# GeoIP

Creates variables with values depending on the client IP address, using the precompiled [MaxMind](http://www.maxmind.com/) databases.

When using the databases with IPv6 support, IPv4 addresses are looked up as IPv4-mapped IPv6 addresses.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module isn't built
by default; it must be enabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--with-stream_geoip_module`.

The module isn't included in packages and images from
[our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages).

#### NOTE
This module requires the [MaxMind GeoIP](http://www.maxmind.com/app/c) library.



## Configuration Example

```nginx
stream {
    geoip_country         GeoIP.dat;
    geoip_city            GeoLiteCity.dat;

    map $geoip_city_continent_code $nearest_server {
        default        example.com;
        EU          eu.example.com;
        NA          na.example.com;
        AS          as.example.com;
    }
#   ...
}
```



## Directives





### geoip_city

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `geoip_city` file;   |
|------------------------------------------------------------------------------------------|----------------------|
| Default                                                                                  | —                    |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream               |

Specifies a database used to determine the country, region, and city depending on the client IP address. The following variables are available when using this database:

| `$geoip_city_continent_code`   | two-letter continent code, for example, "EU", "NA".                                                                                                                                       |
|--------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `$geoip_city_country_code`     | two-letter country code, for example, "RU", "US".                                                                                                                                         |
| `$geoip_city_country_code3`    | three-letter country code, for example, "RUS", "USA".                                                                                                                                     |
| `$geoip_city_country_name`     | country name, for example, "Russian Federation", "United States".                                                                                                                         |
| `$geoip_dma_code`              | DMA region code in the US (also known as "metro code"), according to the [geotargeting](https://developers.google.com/adwords/api/docs/appendix/cities-DMAregions) in Google AdWords API. |
| `$geoip_latitude`              | latitude.                                                                                                                                                                                 |
| `$geoip_longitude`             | longitude.                                                                                                                                                                                |
| `$geoip_region`                | two-symbol country region code (region, territory, state, province, federal land and the like), for example, "48", "DC".                                                                  |
| `$geoip_region_name`           | country region name (region, territory, state, province, federal land and the like), for example, "Moscow City", "District of Columbia".                                                  |
| `$geoip_city`                  | city name, for example, "Moscow", "Washington".                                                                                                                                           |
| `$geoip_postal_code`           | postal code.                                                                                                                                                                              |





### geoip_country

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `geoip_country` file;   |
|------------------------------------------------------------------------------------------|-------------------------|
| Default                                                                                  | —                       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream                  |

Specifies a database used to determine the country depending on the client IP address. The following variables are available when using this database:

| `$geoip_country_code`   | two-letter country code, for example, "RU", "US".                 |
|-------------------------|-------------------------------------------------------------------|
| `$geoip_country_code3`  | three-letter country code, for example, "RUS", "USA".             |
| `$geoip_country_name`   | country name, for example, "Russian Federation", "United States". |





### geoip_org

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `geoip_org` file;   |
|------------------------------------------------------------------------------------------|---------------------|
| Default                                                                                  | —                   |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream              |

Specifies a database used to determine the organization depending on the client IP address. The following variable is available when using this database:

| `$geoip_org`   | organization name, for example, "The University of Melbourne".   |
|----------------|------------------------------------------------------------------|


# https://en.angie.software/angie/docs/configuration/modules/stream/stream_limit_conn.md





# Limit Conn

The module is used to limit the number of connections per the defined key, in particular, the number of connections from a single IP address.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by
default together with the [Stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) module (enabled with
`--with-stream`); it can be disabled with the
[build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure) `--without-stream_limit_conn_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
stream {
    limit_conn_zone $binary_remote_addr zone=addr:10m;

    ...

    server {

        ...

        limit_conn           addr 1;
        limit_conn_log_level error;
    }
}
```



## Directives





### limit_conn

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `limit_conn` zone number;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| Default                                                                                  | —                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server              |

Sets the shared memory zone and the maximum allowed number of connections for a given key value. When this limit is exceeded, the server will close the connection. For example, the directives

```nginx
limit_conn_zone $binary_remote_addr zone=addr:10m;

server {
    ...
    limit_conn addr 1;
}
```

allow only one connection per IP address at a time.

When several `limit_conn` directives are specified, any configured limit will apply.

These directives are inherited from the previous configuration level if and only if there are no `limit_conn` directives defined on the current level.





### limit_conn_dry_run

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `limit_conn_dry_run` `on` | `off`;   |
|------------------------------------------------------------------------------------------|--------------------------------------|
| Default                                                                                  | `limit_conn_dry_run off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                       |

Enables the dry run mode. In this mode, the number of connections is not limited, however, in the [shared memory zone](#s-limit-conn-zone), the number of excessive connections is accounted as usual.





### limit_conn_log_level

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `limit_conn_log_level` `info` | `notice` | `warn` | `error`;   |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------|
| Default                                                                                  | `limit_conn_log_level error;`                                  |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                                                 |

Sets the desired logging level for cases when the server limits the number of connections.





### limit_conn_zone

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `limit_conn_zone` key zone = name:size;   |
|------------------------------------------------------------------------------------------|-------------------------------------------|
| Default                                                                                  | —                                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream                                    |

Sets parameters for a shared memory zone that will keep states for various keys. In particular, the state includes the current number of connections. The key can contain [variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables). Connections with an empty key value are not accounted.

Usage example:

```nginx
limit_conn_zone $binary_remote_addr zone=addr:10m;
```

Here, a client IP address is set by the `$binary_remote_addr` variable.

The size of `$binary_remote_addr` is 4 bytes for IPv4 addresses or 16 bytes for IPv6 addresses. The stored state always occupies 32 or 64 bytes on 32-bit platforms and 64 bytes on 64-bit platforms.

One megabyte zone can keep about 32 thousand 32-byte states or about 16 thousand 64-byte states. If the zone storage is exhausted, the server will close the connection.



## Built-in Variables



### `$limit_conn_status`

keeps the result of limiting the number of connections: `PASSED`,
`REJECTED` or `REJECTED_DRY_RUN`


# https://en.angie.software/angie/docs/configuration/modules/stream/stream_log.md





# Log

The module writes request logs in the specified format.



## Configuration Example

```nginx
log_format basic '$remote_addr [$time_local] '
                 '$protocol $status $bytes_sent $bytes_received '
                 '$session_time';

access_log /spool/logs/angie-access.log basic buffer=32k;
```



## Directives





### access_log

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `access_log` path [format [`buffer=`size] [gzip[=level]] [`flush=`time] [`if=`condition]];

`access_log` `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `access_log off;`                                                                                                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                                                                                                            |

Sets the path, format, and configuration for a buffered log write. Several logs can be specified on the same configuration level. Logging to [syslog](https://en.angie.software//angie/docs/configuration/processing.md#syslog-logging) can be configured by specifying the "syslog:" prefix in the first parameter. The special value off cancels all access_log directives on the current level.

If either the `buffer` or `gzip` parameter is used, writes to log
will be buffered.

#### WARNING
The buffer size must not exceed the size of an atomic write to a disk file. For FreeBSD this size is unlimited.

When buffering is enabled, the data will be written to the file:

* if the next log line does not fit into the buffer;
* if the buffered data is older than the time interval specified by the `flush` parameter;
* when a worker process is [re-opening log files](https://en.angie.software//angie/docs/configuration/runtime.md#log-rotation) or is shutting down.

If the `gzip` parameter is used, then the buffer will be compressed before
writing to the file. The compression level can be set between `1`
(fastest, less compression) and `9` (slowest, best compression). By
default, a buffer size of `64K` bytes and compression level `1` are
used. The data is compressed in atomic blocks, and at any time the log file can
be decompressed or read by the `"zcat"` utility.

Example:

```nginx
access_log /path/to/log.gz basic gzip flush=5m;
```

#### NOTE
For gzip compression support, Angie must be built with the zlib library.

The file path can contain [variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables), but such logs have some constraints:

* the [user](https://en.angie.software//angie/docs/configuration/modules/core.md#user) whose credentials are used by worker processes should have permissions to create files in a directory with such logs;
* buffering does not work;
* the file is opened for each log write and closed immediately after writing. However, since descriptors of frequently used files can be stored in a cache, writing may continue to the old file during log rotation for the time specified by the valid parameter of the [open_log_file_cache](https://en.angie.software//angie/docs/configuration/modules/http/http_log.md#open-log-file-cache) directive.

The if parameter enables conditional logging. A session will not be logged if the condition evaluates to "0" or an empty string.





### log_format

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `log_format` name [`escape=``default` | `json` | `none`] string ...;   |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------|
| Default                                                                                  | —                                                                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream                                                                 |

Specifies the log format, for example:

```nginx
log_format proxy '$remote_addr [$time_local] '
                 '$protocol $status $bytes_sent $bytes_received '
                 '$session_time "$upstream_addr" '
                 '"$upstream_bytes_sent" "$upstream_bytes_received" "$upstream_connect_time"';
```

The `escape` parameter allows setting `json` or `default` character escaping in variables; by default, `default` is used. The `none` value disables character escaping.

When using `default`, characters """, "\\", and characters with values less than 32 or greater than 126 are escaped as "\\xXX". If the variable value is not found, a hyphen "-" will be logged.

When using `json`, all characters not allowed in JSON strings are escaped: characters """ and "\\" are escaped as "\\"" and "\\\\", characters with values less than 32 are escaped as "\\n", "\\r", "\\t", "\\b", "\\f", or "\\u00XX".





### open_log_file_cache

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `open_log_file_cache` `max=`N [`inactive=`time] [`min_uses=`N] [`valid=`time];

`open_log_file_cache` `off`;   |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `open_log_file_cache off;`                                                                                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                                                                                                         |

Defines a cache that stores the file descriptors of frequently used logs whose names contain variables. The directive has the following parameters:

| `max`      | Sets the maximum number of descriptors in the cache; when the cache overflows, the least recently used (LRU) descriptors are closed.                    |
|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
| `inactive` | Sets the time after which a cached descriptor is closed if there were no accesses during this time; by default, 10 seconds.                             |
| `min_uses` | Sets the minimum number of file uses during the time defined by the `inactive` parameter for the descriptor to remain open in the cache; by default, 1. |
| `valid`    | Sets the time after which it should be checked that the file still exists with the same name; by default, 60 seconds.                                   |
| `off`      | Disables caching.                                                                                                                                       |

Usage example:

```nginx
open_log_file_cache max=1000 inactive=20s valid=1m min_uses=2;
```


# https://en.angie.software/angie/docs/configuration/modules/stream/stream_map.md





# Map

Creates variables whose values depend on values of other variables.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by
default together with the [Stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) module (enabled with
`--with-stream`); it can be disabled with the
[build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure) `--without-stream_map_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
map $remote_addr $limit {
    127.0.0.1    "";
    default      $binary_remote_addr;
}

limit_conn_zone $limit zone=addr:10m;
limit_conn addr 1;
```



## Directives





### map

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `map` string $variable { ... };   |
|------------------------------------------------------------------------------------------|-----------------------------------|
| Default                                                                                  | —                                 |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream                            |

Creates a new variable.
Its value depends on the first parameter, specified as a [string with variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables),
for example:

```nginx
set $var1 "foo";
set $var2 "bar";

map $var1$var2 $new_variable {
    default "foobar_value";
}
```

Here, the variable `$new_variable` will have a value
composed of the two variables `$var1` and `$var2`,
or a default value if these variables are not defined.

#### NOTE
Since variables are evaluated only when they are used, the mere declaration even of a large number of "map" variables does not add any extra costs to request processing.

Parameters inside the `map` block specify a mapping between source and resulting values.

Source values are specified as strings or regular expressions.

Strings are matched ignoring the case.

A regular expression should either start with a `~` symbol for a case-sensitive matching, or with the `~*` symbols for case-insensitive matching. A regular expression can contain named and positional captures that can later be used in other directives along with the resulting variable.

If a source value matches one of the names of special parameters described below, it should be prefixed with the `\` symbol.

The resulting value can contain text, variable and their combination.

The following special parameters are also supported:

| `default` value   | sets the resulting value if the source value matches none of the specified variants. When default is not specified, the default resulting value will be an empty string.   |
|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `hostnames`       | indicates that source values can be hostnames with a prefix or suffix mask. This parameter should be specified before the list of values.                                  |

For example,

```nginx
*.example.com 1;
example.*     1;
```

The following two records

```nginx
example.com   1;
*.example.com 1;
```

can be combined:

```nginx
.example.com  1;
```

| `include` file   | includes a file with values. There can be several inclusions.   |
|------------------|-----------------------------------------------------------------|
| `volatile`       | indicates that the variable is not cacheable.                   |

If the source value matches more than one of the specified variants, e.g. both a mask and a regular expression match, the first matching variant will be chosen, in the following order of priority:

1. String value without a mask
2. Longest string value with a prefix mask, e.g. `*.example.com`
3. Longest string value with a suffix mask, e.g. `mail.*`
4. First matching regular expression (in order of appearance in a configuration file)
5. Default value (`default`)





### map_hash_bucket_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `map_hash_bucket_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `map_hash_bucket_size 32|64|128;`                                                                                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream                                                                                                                |

Sets the bucket size for the [map](#s-map) variables hash tables. Default value depends on the processor's cache line size. The details of setting up hash tables are provided [separately](https://en.angie.software//angie/docs/configuration/configfile.md#configure-hashes).





### map_hash_max_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `map_hash_max_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `map_hash_max_size 2048;`                                                                                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream                                                                                                             |

Sets the maximum size of the [map](#s-map) variables hash tables. The details of setting up hash tables are provided [separately](https://en.angie.software//angie/docs/configuration/configfile.md#configure-hashes).


# https://en.angie.software/angie/docs/configuration/modules/stream/stream_metric.md





# Metric

#### Versionadded
Added in version 1.12.0.

The `ngx_stream_metric_module` module allows creating arbitrary
real-time calculated metrics for stream (TCP and UDP) traffic. These metric
values are stored in shared memory and displayed in real-time within the
`/status/stream/metric_zones/` API branch. Various data aggregation
types are supported (counters, histograms, moving averages, etc.) with
grouping by arbitrary keys.

For the response schema, see the
[Stream metric zone API reference](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-stream-metric-zones).



## Configuration Example

Counting connections by client address:

```nginx
stream {
    metric_zone connections:1m count;

    server {
        listen 12345;

        metric connections $remote_addr on=connect;
    }
}

http {
    server {
        listen 80;

        location /status/ {
            allow 127.0.0.1;
            deny all;
            api /status/;
        }
    }
}
```

If a connection is made to port `12345`:

```console
$ nc 127.0.0.1 12345 

## Directives





### metric

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `metric` name key=value [`on`=`connect`| `preread`| `end`];   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------|
| Default                                                                                  | —                                                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                                                |

Calculates the value of the metric for the specified shared memory zone name.

Parameters:

- key — an arbitrary string (often a [variable](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables)) used for grouping values.
  : Maximum length is 255 bytes; longer keys are truncated. In API output,
    Angie appends `...` to every 255-byte key, including one whose
    original length was exactly 255 bytes. A key may itself contain
    `=` characters — only the text after the last `=` is
    treated as the value, so everything before it (including any embedded
    `=`) becomes the key;
- value — a number (can be a variable) processed by the selected mode.
  : If omitted, it defaults to `0`. If the parameter cannot be
    converted to a number, it defaults to `1`;
- `on` — an optional parameter specifying at which point of
  [session processing](https://en.angie.software//angie/docs/configuration/processing.md#stream-sessions) the metric is calculated:
  - If `on=connect`, calculation occurs during the `Pre-access`
    phase, before any data is read from the client;
  - If `on=preread`, calculation occurs once per session, when the
    first data from the upstream side — received from the server proxied to
    with [proxy_pass](https://en.angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-pass), or generated by
    [return](https://en.angie.software//angie/docs/configuration/modules/stream/stream_return.md#s-return) — is sent to the client; by that point, modules
    such as `proxy_protocol`, [ssl_preread](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl_preread.md#s-ssl-preread), and
    `mqtt_preread` have already processed the client's initial data;
  - If `on=end` (default), calculation occurs during the `Log`
    phase, when the session ends.

Example usage:

```nginx
metric sessions $remote_addr=$session_time on=end;
```

#### NOTE
Metrics with an empty key or an invalid `key=value` pair are ignored.
An omitted value is treated as `0`:

```nginx
metric foo $bar;  # Equivalent to $bar=0
```

This is useful, for example, for the `count` mode, which ignores
numerical values and simply reacts to the fact that a metric was updated.

#### NOTE
Remember that variables are evaluated in different phases. For example,
it is impossible to use `$upstream_bytes_sent` (bytes sent to the
upstream) with `on=connect` (before the connection has been
proxied anywhere).





### metric_complex_zone

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `metric_complex_zone` name:size [`expire`=`on`| `off`] [`discard_key`=`name`] { ... }   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
| Default                                                                                  | —                                                                                       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream                                                                                  |

Defines a complex metric — a set of metrics with independent modes.
Each line in the block body defines a submetric name, a mode,
and optional mode parameters.
The zone size must be at least eight system memory pages.

Example usage:

```nginx
metric_complex_zone sessions:1m expire=on discard_key="old" {
    # submetric name   mode          parameters
    min_time           min;
    avg_time           average exp   factor=60;
    max_time           max;
    total              count;
}
```

In the API tree, such a complex metric template looks as follows:

```json
{
    "discarded": 3,
    "metrics": {
        "key1": {
            "min_time": 20,
            "avg_time": 50,
            "max_time": 80,
            "total": 2
        },
        "old": {
             "min_time": 3,
             "avg_time": 40,
             "max_time": 152,
             "total": 80
        }
    }
}
```





### metric_zone

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `metric_zone` name:size [`expire`=`on`| `off`] [`discard_key`=`name`] mode [parameters];   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|
| Default                                                                                  | —                                                                                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream                                                                                     |

Creates a shared memory zone of the specified size with the given name
to store metrics. The zone name serves as a node in the
`/status/stream/metric_zones/` branch.
The zone size must be at least eight system memory pages.

Parameters:

- `expire=` — behavior when the zone is full:
  - If `on`, the oldest metrics (by update time) are discarded to
    : free memory for new ones;
  - If `off` (default) — new incoming metrics are discarded,
    : preserving existing entries.
- `discard_key=` — defines a metric with the key name
  : where values of discarded metrics are accumulated. By default, no such
    metric is created. Reserved key cannot be updated manually.
- mode — data processing algorithm (see the [Operation Modes](#s-metric-modes) section);
- parameters — additional settings for the selected mode
  : (e.g., `factor` for `average exp`).

Example usage:

```nginx
metric_zone session_time:1m max;
```

In the API tree, the shared memory zone template looks as follows:

```json
{
    "discarded": 0,
    "metrics": {
        "key1": 123,
        "key2": 10.5
    }
}
```

#### NOTE
In a 1 MB zone, with a key size of 39 bytes and a single metric mode,
approximately 8,000 unique key entries can be stored.



## Operation Modes

List of available metric operation modes:

* `count` — counter;
* `gauge` — gauge (increment/decrement);
* `last` — the last received value;
* `min` — minimum value;
* `max` — maximum value;
* `average exp` — exponential moving average (EMA) (parameter `factor`);
* `average mean` — mean over a window (parameters `window` and `count`);
* `histogram` — distribution across "buckets" (a list of threshold values).

The examples below use the `/status/` endpoint from the
[configuration example](#configuration-example-107). Each result is
available under `/status/stream/metric_zones//metrics/`.



### count

Each metric update increments the counter by `1`, regardless of the
supplied value.

Default value — `0`.

Examples:

```nginx
metric_zone count:1m count;

# As part of a complex metric:
#
# metric_complex_zone count:1m {
#     some_metric_name  count;
# }

server {
    listen 12345;

    metric count KEY;
}
```

Updating the metric:

```console
$ nc 127.0.0.1 12345 

### gauge

The gauge increases or decreases its value depending on the sign of the
passed number. A positive value increases the counter, while a negative
value decreases it. A value of `0` does not change the counter.

Default value — `0`.

Examples:

```nginx
metric_zone gauge:1m gauge;

# As part of a complex metric:
#
# metric_complex_zone gauge:1m {
#     some_metric_name  gauge;
# }

server {
    listen 12351;
    metric gauge KEY;
}

server {
    listen 12352;
    metric gauge KEY=5;
}

server {
    listen 12353;
    metric gauge KEY=-5;
}

server {
    listen 12354;
    metric gauge KEY=8;
}
```

Updating the metric:

```console
$ nc 127.0.0.1 12351 

### last

Stores the last received value without any aggregation. If value is
omitted, `0` is used.

Examples:

```nginx
metric_zone last:1m last;

# As part of a complex metric:
#
# metric_complex_zone last:1m {
#     some_metric_name  last;
# }

server {
    listen 12361;
    metric last KEY;
}

server {
    listen 12362;
    metric last KEY=8000;
}

server {
    listen 12363;
    metric last KEY=37;
}

server {
    listen 12364;
    metric last KEY=-3.5;
}
```

Updating the metric:

```console
$ nc 127.0.0.1 12361 

### min

Saves the minimum of two values — the currently stored value and the new one.

Examples:

```nginx
metric_zone min:1m min;

# As part of a complex metric:
#
# metric_complex_zone min:1m {
#     some_metric_name  min;
# }

server {
    listen 12371;
    metric min KEY=42.999;
}

server {
    listen 12372;
    metric min KEY=-512;
}

server {
    listen 12373;
    metric min KEY=1;
}
```

Updating the metric:

```console
$ nc 127.0.0.1 12371 

### max

Saves the maximum of two values — the currently stored value and the new one.

Examples:

```nginx
metric_zone max:1m max;

# As part of a complex metric:
#
# metric_complex_zone max:1m {
#     some_metric_name  max;
# }

server {
    listen 12381;
    metric max KEY=42.999;
}

server {
    listen 12382;
    metric max KEY=-512;
}

server {
    listen 12383;
    metric max KEY=1;
}
```

Updating the metric:

```console
$ nc 127.0.0.1 12381 

### average exp

Calculates the average value using the
[exponential smoothing](https://en.wikipedia.org/wiki/Exponential_smoothing) algorithm.

Accepts an optional parameter `factor=` — a coefficient determining
how much the new value influences the average. Integer values from `0` to
`99` are allowed. Default is `90`.

The higher the coefficient, the more weight new values have. If you specify
`90`, the result will be `90%` of the new value and `10%`
of the previous average.

Examples:

```nginx
metric_zone avg_exp:1m average exp factor=60;

# As part of a complex metric:
#
# metric_complex_zone avg_exp:1m {
#     some_metric_name  average exp  factor=60;
# }

server {
    listen 12391;
    metric avg_exp KEY=100;
}

server {
    listen 12392;
    metric avg_exp KEY=200;
}

server {
    listen 12393;
    metric avg_exp KEY=0;
}

server {
    listen 12394;
    metric avg_exp KEY=8;
}

server {
    listen 12395;
    metric avg_exp KEY=30;
}
```

Updating the metric:

```console
$ nc 127.0.0.1 12391 

### average mean

Calculates the arithmetic mean. Accepts optional parameters
`window=` and `count=`, defining the
time interval and sample size for averaging, respectively.
Defaults: `window=off` (entire sample used) and `count=10`.

#### NOTE
For example, `window=5s` will only consider events from the last 5 seconds.
The `window` parameter cannot be `0`. The `count=number`
parameter controls the sample size (cached values) for a smoother mean calculation.

Examples:

```nginx
metric_zone avg_mean:1m average mean window=5s count=8;

# As part of a complex metric:
#
# metric_complex_zone avg_mean:1m {
#     some_metric_name  average mean  window=5s count=8;
# }

server {
    listen 12401;
    metric avg_mean KEY=0.1;
}

server {
    listen 12402;
    metric avg_mean KEY=0.4;
}

server {
    listen 12403;
    metric avg_mean KEY=10;
}

server {
    listen 12404;
    metric avg_mean KEY=1;
}
```

Updating the metric:

```console
$ nc 127.0.0.1 12401 

### histogram

Creates a set of "buckets," incrementing the relevant counter if the new
value does not exceed the bucket threshold. Parameters are provided as
a list of numerical thresholds. Useful for analyzing distributions,
such as session durations.

Mandatory parameters are numbers — the threshold values of the buckets,
typically listed in ascending order.

#### NOTE
The bucket value `inf` or `+Inf` can be used to capture all
values exceeding the highest specified bucket.

Examples:

```nginx
metric_zone hist:1m histogram 0.1 0.2 0.5 1 2 inf;

# As part of a complex metric:
#
# metric_complex_zone hist:1m {
#     some_metric_name  histogram  0.1 0.2 0.5 1 2 inf;
# }

server {
    listen 12411;
    metric hist KEY=0.25;
}

server {
    listen 12412;
    metric hist KEY=2;
}

server {
    listen 12413;
    metric hist KEY=1000;
}
```

Updating the metric:

```console
$ nc 127.0.0.1 12411 

## Built-in Variables

Variables are created for each metric:

- `$metric_`
- `$metric__key`
- `$metric__value`

For complex metrics, an additional variable is added:

- `$metric__value_`



### `$metric_`

Similar to the [metric](#s-metric) directive, the `$metric_`
variable setter can be used to update a metric. Calculation occurs when the
variable is set — for example, via the [set](https://en.angie.software//angie/docs/configuration/modules/stream/stream_set.md#s-set) directive, which is
evaluated during the `Pre-access` [phase](https://en.angie.software//angie/docs/configuration/processing.md#stream-sessions) (the
same stage as `on=connect`), or programmatically from the
[Stream JS](https://en.angie.software//angie/docs/configuration/modules/external-modules/stream_js.md#stream-js) module, for example in a
[js_access](https://en.angie.software//angie/docs/configuration/modules/external-modules/stream_js.md#s-js-access) handler.

The setter accepts a key with an optional `=value` suffix. The last
`=` separates the key from the value; without the suffix, the value is
`0`. The key and value can contain text, variables, or combinations of
both. These are the same parsing rules as for [metric](#s-metric).

Example usage:

```nginx
stream {
    metric_zone hits:1m count;

    # At this point, the $metric_hits variable is added

    server {
        listen 12345;

        metric hits client=1 on=connect;
    }

    server {
        listen 12346;

        set $metric_hits client=1;

        return "$metric_hits\n";
    }
}
```

After three connections to port `12345` and one connection to port
`12346`:

```console
$ nc 127.0.0.1 12345 ` back returns the key together with the
metric's current calculated value, in `key=value` form — not the
literal string that was assigned. In the example above, the connection
assigns the literal value `client=1`, but since the `count`
mode ignores the assigned value and simply increments on every update,
reading `$metric_hits` afterward returns `client=4` — the
counter's new total, which already includes the three prior updates from
port `12345`.

Additionally, the value stored in the `$metric__key` variable
changes to the specified key.





### `$metric__key` and `$metric__value`

The `$metric__key` and `$metric__value` variables
define the key and value respectively. The metric update occurs when the
`$metric__value` is set, provided that the key in
`$metric__key` has already been defined.

#### NOTE
For complex metrics, the submetric values in the `$metric__value`
variable are joined using a `", "` separator.

Example usage:

```nginx
stream {
    metric_zone level:1m gauge;

    # The variables $metric_level, $metric_level_key, and $metric_level_value are added here.

    metric_complex_zone stats:1m {
        count count;
        min   min;
        avg   average exp;
    }

    # $metric_stats, $metric_stats_key, and $metric_stats_value are added here.

    server {
        listen 12345;

        metric level sensor=10 on=connect;
    }

    server {
        listen 12346;

        set $metric_level_key   "sensor";
        set $metric_level_value 5;

        # Or: set $metric_level sensor=5;

        return "Updated with '$metric_level'\nValue='$metric_level_value'\n";
    }

    server {
        listen 12347;

        set $metric_stats_key   bar;
        set $metric_stats_value 9;

        # Or: set $metric_stats bar=9;

        return "Updated with '$metric_stats'\nValues='$metric_stats_value'\n";
    }
}
```

With this configuration, a connection to port `12345` (setting the
gauge's starting value to `10`) followed by a connection to port
`12346` yields:

```console
$ nc 127.0.0.1 12345 _value`, the value is
recognized as `0`. If the string consists of characters that cannot be
converted to a number, it is recognized as `1`.

Calculation occurs only after both `$metric__key` and
`$metric__value` have been set.

In this case, the value stored in `$metric_` becomes equal
to the new, calculated `key=value` pair, not the literal values
just assigned.

The value in `$metric__key` represents the last key specified
via variables.

The value in `$metric__value` represents the last calculated
value for the key set in `$metric__key`.



### `$metric__value_`

For complex metrics, the value of a specific submetric can be retrieved
using the `$metric__value_` variable, where
 is the name of the submetric.

Example usage:

```nginx
stream {
    metric_complex_zone foo:1m {
        count count;
        min   min;
        avg   average exp;
    }

    # Adds $metric_foo, $metric_foo_key, $metric_foo_value,
    # and $metric_foo_value_count, $metric_foo_value_min, $metric_foo_value_avg.

    server {
        listen 12345;

        set $metric_foo_key   bar;
        set $metric_foo_value 9;

        # Or: set $metric_foo bar=9;

        return "Updated with '$metric_foo'\nValues='$metric_foo_value'\nCount='$metric_foo_value_count'\n";
    }
}
```

With this configuration, a connection to port `12345` yields:

```console
$ nc 127.0.0.1 12345 

## Additional Examples



### Monitoring Connections by Protocol

```nginx
metric_zone protocols:1m count;

server {
    listen 12345;
    listen 12346 udp;

    metric protocols $protocol;
}
```

Response:

```json
{
    "TCP": 340,
    "UDP": 58
}
```



### Upstream Session Time Distribution

```nginx
metric_zone upstream_time:10m expire=on histogram
    0.05 0.1 0.3 0.5 1 2 5 10 inf;

server {
    listen 12345;

    proxy_pass backend;
    metric upstream_time $upstream_addr=$upstream_session_time on=end;
}
```

Response:

```json
{
    "discarded": 0,
    "metrics": {
        "backend1:8080": {
            "0.05": 12,
            "0.1": 28,
            "0.3": 56,
            "0.5": 78,
            "1": 92,
            "2": 97,
            "5": 99,
            "10": 100,
            "inf": 100
        }
    }
}
```



### Active Connections

```nginx
stream {
    metric_zone active_connections:2m gauge;

    server {
        listen 12345;

        metric active_connections service_a=1 on=connect;
        metric active_connections service_a=-1 on=end;
    }

    server {
        listen 12346;

        metric active_connections service_b=1 on=connect;
        metric active_connections service_b=-1 on=end;
    }
}

http {
    server {
        listen 8080;

        location /connections/ {
            allow 127.0.0.1;
            deny all;
            api /status/stream/metric_zones/active_connections/metrics/;
        }
    }
}
```

Response:

```json
{
    "service_a": 42,
    "service_b": 17
}
```



## Prometheus Support

Angie includes a built-in [Prometheus](https://en.angie.software//angie/docs/configuration/modules/http/http_prometheus.md#http-prometheus) module for
displaying metrics in
[Prometheus format](https://prometheus.io/docs/instrumenting/exposition_formats/),
which supports custom metrics, including those collected on the stream side.
Since Prometheus exposition is an HTTP-only feature, the
[prometheus_template](https://en.angie.software//angie/docs/configuration/modules/http/http_prometheus.md#prometheus-template) and [prometheus](https://en.angie.software//angie/docs/configuration/modules/http/http_prometheus.md#id1)
directives are configured in an `http` block, referencing the stream
metric zone through the same unified `/status/` API tree.

As an integration example, consider the following configuration:

```nginx
stream {
    # Creating the "upload" metric
    metric_complex_zone upload:1m discard_key="other" {
        stats    histogram 64 256 1024 4096 16384 +Inf;
        sum      gauge;
        count    count;
        avg_size average exp;
    }

    upstream backend {
        server 127.0.0.1:15001;
    }

    server {
        listen 12345;

        # Updating the metric at session end with the total
        # number of bytes received from the client
        proxy_pass backend;
        metric upload angie=$bytes_received on=end;
    }
}

http {
    # Describing the Prometheus template for the "upload" metric
    prometheus_template upload_metric {
        'stats{le="$1"}' $p8s_value
                         path=~^/stream/metric_zones/upload/metrics/angie/stats/(.+)$
                         type=histogram;

        'stats_sum'      $p8s_value
                         path=/stream/metric_zones/upload/metrics/angie/sum;
        'stats_count'    $p8s_value
                         path=/stream/metric_zones/upload/metrics/angie/count;

        'avg_size'       $p8s_value
                         path=/stream/metric_zones/upload/metrics/angie/avg_size;
    }

    server {
        listen 80;

        # Target for metric scraping
        location /prometheus/upload_metric/ {
            prometheus upload_metric;
        }
    }
}
```

After five connections to port `12345`, sending payloads of
`16384`, `64448`, `64`, `1028`, and `1028`
bytes:

```console
$ head -c 16384 /dev/urandom | nc 127.0.0.1 12345
$ head -c 64448 /dev/urandom | nc 127.0.0.1 12345
$ head -c 64 /dev/urandom | nc 127.0.0.1 12345
$ head -c 1028 /dev/urandom | nc 127.0.0.1 12345
$ head -c 1028 /dev/urandom | nc 127.0.0.1 12345
```

The metric values will be:

```json
{
    "stats": {
        "64": 1,
        "256": 1,
        "1024": 1,
        "4096": 3,
        "16384": 4,
        "+Inf": 5
    },

    "sum": 82952,
    "count": 5,
    "avg_size": 1077.9376
}
```

In [Prometheus format](https://prometheus.io/docs/instrumenting/exposition_formats/),
the metric is available at `/prometheus/upload_metric/`:

```text
# Angie Prometheus template "upload_metric"
# TYPE stats histogram
stats{le="64"} 1
stats{le="256"} 1
stats{le="1024"} 1
stats{le="4096"} 3
stats{le="16384"} 4
stats{le="+Inf"} 5
stats_sum 82952
stats_count 5
avg_size 1077.9376
```


# https://en.angie.software/angie/docs/configuration/modules/stream/stream_mqtt_preread.md





# MQTT Preread

Enables extracting client IDs and usernames
from `CONNECT` packets for Message Queuing Telemetry Transport (MQTT)
versions
[3.1.1](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc398718028)
and
[5.0](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901033).

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module isn't built
by default; it must be enabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--with-stream_mqtt_preread_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example



### Choosing a server in a group by client ID:

```nginx
stream {

    mqtt_preread on;

    upstream mqtt {
        hash $mqtt_preread_clientid;
        # ...
    }
}
```



## Directives





### mqtt_preread

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `mqtt_preread` `on` | `off`;   |
|------------------------------------------------------------------------------------------|--------------------------------|
| Default                                                                                  | `mqtt_preread off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                 |

Controls extracting information from `CONNECT` packets
during the
[preread phase](https://en.angie.software//angie/docs/configuration/processing.md#stream-sessions).
If the parameter is enabled (`on`),
the variables listed below are populated
in the context where it is specified.



## Built-in Variables

For detailed description of value semantics,
see the MQTT protocol specification versions
[3.1.1](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc398718031)
and [5.0](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901033).



### `$mqtt_preread_clientid`

Unique client identifier.



### `$mqtt_preread_username`

Optional username.


# https://en.angie.software/angie/docs/configuration/modules/stream/stream_pass.md





# Pass

Allows passing the accepted connection directly to any configured listening
socket in [HTTP](https://en.angie.software//angie/docs/configuration/modules/index.md#modules-http), [Stream](https://en.angie.software//angie/docs/configuration/modules/index.md#modules-stream), or
[Mail](https://en.angie.software//angie/docs/configuration/modules/index.md#modules-mail) modules.

The module enables selective SSL termination based on SNI.



## Configuration Example

After the `stream` module handles the SSL/TLS termination,
it forwards the connection to the `http` module:

```nginx
stream {

    server {

        listen 8000 default_server;
        ssl_preread on;
        # ...
    }

    server {

        listen 8000;
        server_name foo.example.com;
        pass 127.0.0.1:8001; # to HTTP
    }

    server {

        listen 8000;
        server_name bar.example.com;
        # ...
    }
}

http {

    server {

        listen 8001 ssl;
        # ...

        location / {

            root html;
        }
    }
}
```



## Directives





### pass

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `pass` address;   |
|------------------------------------------------------------------------------------------|-------------------|
| Default                                                                                  | —                 |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | server            |

This directive sets the server address to which the client connection should be
passed. The address can be given as an IP address and port:

```nginx
pass 127.0.0.1:12345;
```

Or as a path to a UNIX domain socket:

```nginx
pass unix:/tmp/stream.socket;
```

Also, the address can be set with [variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables):

```nginx
pass $upstream;
```


# https://en.angie.software/angie/docs/configuration/modules/stream/stream_proxy.md







# Proxy

Allows proxying data streams over TCP, UDP, and UNIX domain sockets.



## Configuration Example

```nginx
server {
    listen 127.0.0.1:12345;
    proxy_pass 127.0.0.1:8080;
}

server {
    listen 12345;
    proxy_connect_timeout 1s;
    proxy_timeout 1m;
    proxy_pass example.com:12345;
}

server {
    listen 53 udp reuseport;
    proxy_timeout 20s;
    proxy_pass dns.example.com:53;
}

server {
    listen [::1]:12345;
    proxy_pass unix:/tmp/stream.socket;
}
```



## Directives





### proxy_bind

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_bind` address [`transparent`] | `off`;   |
|------------------------------------------------------------------------------------------|-------------------------------------------------|
| Default                                                                                  | —                                               |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                                  |

Makes outgoing connections to a proxied server originate from the specified local IP address. Parameter value can contain [variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables). The special value `off` cancels the effect of the proxy_bind directive inherited from the previous configuration level, which allows the system to auto-assign the local IP address.

By default, this value is evaluated once when the session is initialized, before
a proxied server is selected. In Angie PRO, evaluation happens after each
proxied server selection (including retries), so the bind address can depend on
the selected server; for example, via the `$upstream_current_addr`
variable. If the evaluated value is empty, no binding is made.

The `transparent` parameter allows outgoing connections to a proxied
server originate from a non-local IP address, for example, from a real IP
address of a client:

```nginx
proxy_bind $remote_addr transparent;
```

For this parameter to work,
Angie worker processes usually need to run
with [superuser](https://en.angie.software//angie/docs/configuration/modules/core.md#user) privileges.
On Linux, this is not required:
if the `transparent` parameter is specified,
worker processes inherit the CAP_NET_RAW capability from the master process.

#### NOTE
The kernel routing table should also be configured
to intercept network traffic from the proxied server.





### proxy_buffer_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_buffer_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `proxy_buffer_size 16k;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                                                                                                     |

Sets the size of the buffer used for reading data from the proxied server. Also sets the size of the buffer used for reading data from the client.





### proxy_connect_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_connect_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `proxy_connect_timeout 60s;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                                                                                                         |

Defines a timeout for establishing a connection with a proxied server.





### proxy_connection_drop

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_connection_drop` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units) | `on` | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `proxy_connection_drop off;`                                                                                                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                                                                                                                        |

Enables termination of all sessions to the proxied server after it has been
removed from the group or marked as permanently unavailable by a [reresolve](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-reresolve) process or the [API command](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-config-methods)
`DELETE`.

A session is terminated when the next read or write event is processed for
either the client or the proxied server.

Setting time enables a session termination [timeout](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);
with `on` set, sessions are dropped immediately.





### proxy_download_rate

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_download_rate` rate;   |
|------------------------------------------------------------------------------------------|-------------------------------|
| Default                                                                                  | `proxy_download_rate 0;`      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                |

Limits the speed of reading the data from the proxied server. The `rate` is specified in bytes per second.

| `0`   | disables rate limiting   |
|-------|--------------------------|

#### NOTE
The limit is set per a connection, so if Angie simultaneously opens two connections to the proxied server, the overall rate will be twice as much as the specified limit.

Parameter value can contain variables. It may be useful in cases where rate should be limited depending on a certain condition:

```nginx
map $slow $rate {
    1     4k;
    2     8k;
}

proxy_download_rate $rate;
```





### proxy_half_close

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_half_close` `on` | `off`;   |
|------------------------------------------------------------------------------------------|------------------------------------|
| Default                                                                                  | `proxy_half_close off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                     |

Enables or disables closing each direction of a TCP connection independently ("TCP half-close"). If enabled, proxying over TCP will be kept until both sides close the connection.





### proxy_next_upstream

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_next_upstream` `on` | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------------|
| Default                                                                                  | `proxy_next_upstream on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                        |

When a connection to the proxied server cannot be established, determines whether a client connection will be passed to the next server in the [upstream pool](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#stream-upstream).

Passing a connection to the next server can be limited by the [number of tries](#s-proxy-next-upstream-tries) and by [time](#s-proxy-next-upstream-timeout).





### proxy_next_upstream_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_next_upstream_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `proxy_next_upstream_timeout 0;`                                                                                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                                                                                                               |

Limits the time allowed to pass a connection to the [next](#s-proxy-next-upstream) server.

| `0`   | turns off this limitation   |
|-------|-----------------------------|





### proxy_next_upstream_tries

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_next_upstream_tries` number;   |
|------------------------------------------------------------------------------------------|---------------------------------------|
| Default                                                                                  | `proxy_next_upstream_tries 0;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                        |

Limits the number of possible tries for passing a connection to the [next](#s-proxy-next-upstream) server.

| `0`   | turns off this limitation   |
|-------|-----------------------------|





### proxy_pass

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_pass` address;   |
|------------------------------------------------------------------------------------------|-------------------------|
| Default                                                                                  | —                       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | server                  |

Sets the address of a proxied server. The `address` can be specified as a domain name or IP address, and a port:

```nginx
proxy_pass localhost:12345;
```

or as a UNIX domain socket path:

```nginx
proxy_pass unix:/tmp/stream.socket;
```

If a domain name resolves to several addresses, all of them will be used in a round-robin fashion. In addition, an address can be specified as a [server group](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#stream-upstream).

If the referenced group is [portless](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-no-port) (PRO), meaning its
servers are defined without a port, the port is appended to the group name:

```nginx
proxy_pass backend:8443;
```

The port suffix is required for a portless group and is not allowed for a group
whose servers already define ports; violating either rule is a configuration
error.

The address can also be specified using variables
(along with the port suffix, if allowed):

```nginx
proxy_pass $upstream;
```

In this case, the server name is searched among the described [server groups](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#stream-upstream) and, if not found, is determined using a [resolver](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#s-resolver).





### proxy_protocol

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_protocol` `on` | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | `proxy_protocol off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                   |

Enables the [PROXY protocol](http://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) for connections to a proxied server.





### proxy_protocol_tlv

#### Versionadded
Added in version 1.11.0.

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_protocol_tlv` name value;   |
|------------------------------------------------------------------------------------------|------------------------------------|
| Default                                                                                  | —                                  |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                     |

Adds a TLV to the PROXY protocol v2 header sent to a proxied server. The value can contain variables. The name can be a TLV type name or its numeric value; in the latter case, the value is specified in hexadecimal and must start with 0x. For SSL TLVs, use the `ssl_` prefix; the special `ssl_verify` name sets the verify field of the SSL TLV. The directive is used only with [proxy_protocol_version](#s-proxy-protocol-version) set to `2`.





### proxy_protocol_version

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_protocol_version` `1` | `2`;   |
|------------------------------------------------------------------------------------------|---------------------------------------|
| Default                                                                                  | `proxy_protocol_version 1;`           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                        |

Sets the PROXY protocol version used for connections to a proxied server. The setting is effective when [proxy_protocol](#s-proxy-protocol) is enabled. Version 2 allows sending TLVs configured by the [proxy_protocol_tlv](#s-proxy-protocol-tlv) directive.





### proxy_requests

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_requests` number;   |
|------------------------------------------------------------------------------------------|----------------------------|
| Default                                                                                  | `proxy_requests 0;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server             |

Sets the number of client datagrams at which binding between a client and existing UDP stream session is dropped. After receiving the specified number of datagrams, next datagram from the same client starts a new session. The session terminates when all client datagrams are transmitted to a proxied server and the expected [number of responses](#s-proxy-responses) is received, or when it reaches a [timeout](#s-proxy-timeout).





### proxy_responses

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_responses` number;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| Default                                                                                  | —                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server              |

Sets the number of datagrams expected from the proxied server in response to a client datagram if the [UDP](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#stream-protocol) protocol is used. The number serves as a hint for session termination. By default, the number of datagrams is not limited.

If zero value is specified, no response is expected. However, if a response is received and the session is still not finished, the response will be handled.





### proxy_socket_keepalive

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_socket_keepalive` `on` | `off`;   |
|------------------------------------------------------------------------------------------|------------------------------------------|
| Default                                                                                  | `proxy_socket_keepalive off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                           |

Configures the "TCP keepalive" behavior for outgoing connections to a proxied server.

| `off`   | By default, the operating system's settings are in effect for the socket.   |
|---------|-----------------------------------------------------------------------------|
| `on`    | The SO_KEEPALIVE socket option is turned on for the socket.                 |





### proxy_ssl

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_ssl` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| Default                                                                                  | `proxy_ssl off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server              |

Enables the SSL/TLS protocol for connections to a proxied server.





### proxy_ssl_alpn

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_ssl_alpn` protocol ...;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | —                                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                   |

Specifies the list of protocols to advertise via the
[ALPN](https://datatracker.ietf.org/doc/html/rfc7301)
extension when establishing a connection with the proxied server, for example:

```nginx
proxy_ssl_alpn h2 http/1.1;
```

The parameter value can contain variables.





### proxy_ssl_certificate

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_ssl_certificate` file [file];   |
|------------------------------------------------------------------------------------------|----------------------------------------|
| Default                                                                                  | —                                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                         |

Specifies a file with the certificate in the PEM format used for authentication to a proxied server. The file name can contain variables.

When [proxy_ssl_ntls](#s-proxy-ssl-ntls) is enabled, the directive takes two arguments instead of one:

```nginx
server {
    proxy_ssl_ntls  on;

    proxy_ssl_certificate      sign.crt enc.crt;
    proxy_ssl_certificate_key  sign.key enc.key;

    proxy_ssl_ciphers "ECC-SM2-WITH-SM4-SM3:ECDHE-SM2-WITH-SM4-SM3:RSA";

    proxy_pass backend:12345;
}
```





### proxy_ssl_certificate_cache

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_ssl_certificate_cache` `off`;

`proxy_ssl_certificate_cache` `max=`N [`inactive=`time] [`valid=`time];   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `proxy_ssl_certificate_cache off;`                                                                                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                                                                                                          |

Defines a cache that stores [SSL certificates](#s-proxy-ssl-certificate) and [secret keys](#s-proxy-ssl-certificate-key) specified using variables.

The directive supports the following parameters:

- `max` — sets the maximum number of elements in the cache. When the cache
  overflows, the least recently used (LRU) elements are removed.
- `inactive` — defines the time after which an element is removed if it
  has not been accessed during this time, even if still within its
  `valid` period; each access resets this timer. The default is 10
  seconds.
- `valid` — defines the time during which a cached element is considered
  valid and can be reused. The default is 60 seconds. After this period,
  certificates are reloaded or revalidated.
- `off` — disables the cache.

Example:

```nginx
proxy_ssl_certificate       $proxy_ssl_server_name.crt;
proxy_ssl_certificate_key   $proxy_ssl_server_name.key;
proxy_ssl_certificate_cache max=1000 inactive=20s valid=1m;
```





### proxy_ssl_certificate_key

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_ssl_certificate_key` file [file];   |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| Default                                                                                  | —                                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                             |

Specifies a file with the secret key in the PEM format used for authentication to a proxied server.

The value `engine:`name`:id` can be specified instead of the file, which loads a secret key with a specified id from the OpenSSL engine name.

The value `store:scheme:id` can be specified instead of the file, which is used to load a secret key with a specified id and OpenSSL provider registered URI scheme, such as [pkcs11](https://datatracker.ietf.org/doc/html/rfc7512).

The file name can contain variables.

When [proxy_ssl_ntls](#s-proxy-ssl-ntls) is enabled, the directive accepts two arguments instead of one:

```nginx
server {
    proxy_ssl_ntls  on;

    proxy_ssl_certificate      sign.crt enc.crt;
    proxy_ssl_certificate_key  sign.key enc.key;

    proxy_ssl_ciphers "ECC-SM2-WITH-SM4-SM3:ECDHE-SM2-WITH-SM4-SM3:RSA";

    proxy_pass backend:12345;
}
```





### proxy_ssl_ciphers

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_ssl_ciphers` ciphers;   |
|------------------------------------------------------------------------------------------|--------------------------------|
| Default                                                                                  | `proxy_ssl_ciphers DEFAULT;`   |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                 |

Specifies the enabled ciphers for requests to a proxied server. The ciphers are specified in the format understood by the OpenSSL library.

The list of ciphers depends on the version of OpenSSL installed.
The full list can be viewed using the `openssl ciphers` command.

#### WARNING
The `proxy_ssl_ciphers` directive does *not* configure ciphers for TLS 1.3 when
using OpenSSL. To configure TLS 1.3 ciphers with OpenSSL, use the
[proxy_ssl_conf_command](#s-proxy-ssl-conf-command) directive, which was added for advanced
SSL configuration.

- In LibreSSL, TLS 1.3 ciphers *can* be configured using
  `proxy_ssl_ciphers`.
- In BoringSSL, TLS 1.3 ciphers cannot be configured.





### proxy_ssl_conf_command

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_ssl_conf_command` name value;   |
|------------------------------------------------------------------------------------------|----------------------------------------|
| Default                                                                                  | —                                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                         |

Sets arbitrary OpenSSL configuration [commands](https://docs.openssl.org/master/man3/SSL_CONF_cmd/) when establishing a connection with the proxied server.

#### NOTE
The directive is supported when using OpenSSL 1.0.2 or higher.
To configure TLS 1.3 ciphers with OpenSSL, use the `ciphersuites` command.

Several proxy_ssl_conf_command directives can be specified on the same level. These directives are inherited from the previous configuration level if and only if there are no proxy_ssl_conf_command directives defined on the current level.

#### WARNING
Note that configuring OpenSSL directly might result in unexpected behavior.





### proxy_ssl_crl

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_ssl_crl` file;   |
|------------------------------------------------------------------------------------------|-------------------------|
| Default                                                                                  | —                       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server          |

Specifies a file with revoked certificates (CRL) in the PEM format used to [verify](#s-proxy-ssl-verify) the certificate of the proxied server.





### proxy_ssl_keylog_file

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_ssl_keylog_file` file;   |
|------------------------------------------------------------------------------------------|---------------------------------|
| Default                                                                                  | —                               |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                  |

Specifies a file to log SSL/TLS keys for connections to proxied servers in the context,
using the [SSLKEYLOGFILE](https://www.ietf.org/archive/id/draft-thomson-tls-keylogfile-00.html)
format used by tools such as Wireshark to decrypt captured TLS traffic.

The directive should not be used with LibreSSL.

#### WARNING
The file contains sensitive TLS key material that can decrypt captured
traffic for the corresponding connections. Use this directive only for
debugging or protocol analysis, restrict access to the file, and remove it
when no longer needed.





### proxy_ssl_name

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_ssl_name` name;                   |
|------------------------------------------------------------------------------------------|------------------------------------------|
| Default                                                                                  | `proxy_ssl_name` host from `proxy_pass`; |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                           |

Allows overriding the server name used to [verify](#s-proxy-ssl-verify) the certificate of the proxied server and to be [passed through SNI](#s-proxy-ssl-server-name) when establishing a connection with the proxied server. The server name can also be specified using variables.

By default, the host name from the address specified by the [proxy_pass](#s-proxy-pass) directive is used.





### proxy_ssl_ntls

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_ssl_ntls` `on` | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | `proxy_ssl_ntls off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                   |

Enables client-side support for NTLS when using the [TongSuo](https://github.com/Tongsuo-Project/Tongsuo) TLS library.

```nginx
server {
    proxy_ssl_ntls  on;

    proxy_ssl_certificate      sign.crt enc.crt;
    proxy_ssl_certificate_key  sign.key enc.key;

    proxy_ssl_ciphers "ECC-SM2-WITH-SM4-SM3:ECDHE-SM2-WITH-SM4-SM3:RSA";

    proxy_pass backend:12345;
}
```

#### NOTE
Angie must be built using the `--with-ntls` configuration parameter, with the corresponding SSL library with NTLS support

```default
./configure --with-openssl=../Tongsuo-8.3.0 \
            --with-openssl-opt=enable-ntls  \
            --with-ntls
```





### proxy_ssl_password_file

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_ssl_password_file` file;   |
|------------------------------------------------------------------------------------------|-----------------------------------|
| Default                                                                                  | —                                 |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                    |

Specifies a file with passphrases for [secret keys](#s-proxy-ssl-certificate-key) where each passphrase is specified on a separate line. Passphrases are tried in turn when loading the key.





### proxy_ssl_protocols

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_ssl_protocols` [`SSLv2`] [`SSLv3`] [`TLSv1`] [`TLSv1.1`] [`TLSv1.2`] [`TLSv1.3`];   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|
| Default                                                                                  | `proxy_ssl_protocols TLSv1.2 TLSv1.3;`                                                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                                                                             |

Enables the specified protocols for requests to a proxied server.





### proxy_ssl_server_name

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_ssl_server_name` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| Default                                                                                  | `proxy_ssl_server_name off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                          |

Enables or disables passing the server name
specified by the [proxy_ssl_name](#s-proxy-ssl-name) directive
through the
[Server Name Indication](http://en.wikipedia.org/wiki/Server_Name_Indication)
TLS extension
(SNI,
[RFC 6066](https://datatracker.ietf.org/doc/html/rfc6066.html))
when establishing a connection with the proxied server.





### proxy_ssl_session_reuse

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_ssl_session_reuse` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-------------------------------------------|
| Default                                                                                  | `proxy_ssl_session_reuse on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                            |

Determines whether SSL sessions can be reused when working with the proxied server. If the errors "SSL3_GET_FINISHED:digest check failed" appear in the logs, try disabling session reuse.





### proxy_ssl_trusted_certificate

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_ssl_trusted_certificate` file;   |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| Default                                                                                  | —                                       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                          |

Specifies a file with trusted CA certificates in the PEM format used to [verify](#s-proxy-ssl-verify) the certificate of the proxied server.





### proxy_ssl_verify

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_ssl_verify` `on` | `off`;   |
|------------------------------------------------------------------------------------------|------------------------------------|
| Default                                                                                  | `proxy_ssl_verify off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                     |

Enables or disables verification of the proxied server certificate.





### proxy_ssl_verify_depth

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_ssl_verify_depth` number;   |
|------------------------------------------------------------------------------------------|------------------------------------|
| Default                                                                                  | `proxy_ssl_verify_depth 1;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                     |

Sets the verification depth in the proxied server certificates chain.





### proxy_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `proxy_timeout 10m;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                                                                                                 |

Sets a timeout between two successive read or write operations on client or proxied server connections. If no data is transmitted within this time, the connection is closed.





### proxy_upload_rate

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_upload_rate` rate;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| Default                                                                                  | `proxy_upload_rate 0;`      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server              |

Limits the speed of reading the data from the client. The rate is specified in bytes per second.

| `0`   | disables rate limiting   |
|-------|--------------------------|

#### NOTE
The limit is set per connection, so if the client simultaneously opens two connections, the overall rate will be twice as much as the specified limit.

The parameter value can contain variables. This may be useful in cases where the rate should be limited depending on a certain condition:

```nginx
map $slow $rate {
    1     4k;
    2     8k;
}

proxy_upload_rate $rate;
```


# https://en.angie.software/angie/docs/configuration/modules/stream/stream_rdp_preread.md





# RDP Preread

When using the RDP protocol, this module allows extracting cookies,
which are used for session identification and management,
before making a load balancing decision.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module isn't built
by default; it must be enabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--with-stream_rdp_preread_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example



### Binding to the Cookie-Issuing Server

This configuration uses the `learn` mode of the [sticky](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-sticky) directive:

```nginx
stream {

    rdp_preread on;

    upstream rdp {

        server 127.0.0.1:3390 sid=a;
        server 127.0.0.1:3391 sid=b;

        sticky learn lookup=$rdp_cookie create=$rdp_cookie zone=sessions:1m;
    }
}
```



## Directives





### rdp_preread

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `rdp_preread` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-------------------------------|
| Default                                                                                  | `rdp_preread off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                |

Controls extracting information from RDP protocol cookies
during the
[preread stage](https://en.angie.software//angie/docs/configuration/processing.md#stream-sessions).
If the setting is `on`,
the variables listed below will be populated
in the context where it is specified.



## Built-in Variables

The semantics of cookie values depend on the RDP protocol version.



### `$rdp_cookie`

The entire cookie value.



### `$rdp_cookie_`

The value of the cookie field with the specified name.


# https://en.angie.software/angie/docs/configuration/modules/stream/stream_realip.md





# RealIP

Allows changing the client address and port to those passed in the PROXY protocol header. The PROXY protocol must be previously enabled by setting the `proxy_protocol` parameter in the [listen](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#s-listen) directive.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module isn't built
by default; it must be enabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--with-stream_realip_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
listen 12345 proxy_protocol;

set_real_ip_from  192.168.1.0/24;
set_real_ip_from  192.168.2.1;
set_real_ip_from  2001:0db8::/32;
```



## Directives





### set_real_ip_from

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `set_real_ip_from` address | CIDR | `unix:`;   |
|------------------------------------------------------------------------------------------|------------------------------------------------|
| Default                                                                                  | —                                              |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                                 |

Defines trusted addresses that are known to send correct replacement addresses. If the special value `unix:` is specified, all UNIX domain sockets will be trusted.



## Built-in Variables



### `$realip_remote_addr`

keeps the original client address



### `$realip_remote_port`

keeps the original client port


# https://en.angie.software/angie/docs/configuration/modules/stream/stream_return.md





# Return

Allows sending a specified value to the client and then closing the connection.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by
default together with the [Stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) module (enabled with
`--with-stream`); it can be disabled with the
[build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure) `--without-stream_return_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
server {
    listen 12345;
    return $time_iso8601;
}
```



## Directives





### return

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `return` value;   |
|------------------------------------------------------------------------------------------|-------------------|
| Default                                                                                  | —                 |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | server            |

Specifies a value to send to the client. The value can contain [variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables).


# https://en.angie.software/angie/docs/configuration/modules/stream/stream_set.md





# Set

The module allows setting a value for a variable.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by
default together with the [Stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) module (enabled with
`--with-stream`); it can be disabled with the
[build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure) `--without-stream_set_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
server {
    listen 12345;
    set    $true 1;
}
```



## Directives





### set

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `set` $variable value;   |
|------------------------------------------------------------------------------------------|--------------------------|
| Default                                                                                  | —                        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | server                   |

Sets a value for the specified variable. The value can contain [variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables).


# https://en.angie.software/angie/docs/configuration/modules/stream/stream_split_clients.md





# Split Clients

The module generates variables for A/B testing, canary releases,
and other scenarios that route a specific percentage of clients to one
server or configuration while directing the rest elsewhere.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by
default together with the [Stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) module (enabled with
`--with-stream`); it can be disabled with the
[build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure) `--without-stream_split_clients_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
stream {
    # ...
    split_clients "${remote_addr}AAA" $upstream {
                  0.5%                feature_test1;
                  2.0%                feature_test2;
                  *                   production;
    }

    server {
        # ...
        proxy_pass $upstream;
    }
}
```



## Directives





### split_clients

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `split_clients` string $variable { ... }   |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| Default                                                                                  | —                                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream                                     |

Creates a $variable by hashing the string;
[variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables) in the string are substituted,
the result is hashed,
and the hash value is used to select the string value of the $variable.

The hash function uses
[MurmurHash2](https://en.wikipedia.org/wiki/MurmurHash#MurmurHash2)
(32-bit),
and its entire value range
(0 to 4294967295)
is mapped to buckets in order of appearance;
the percentages determine the size of the buckets.
A wildcard (`*`) may appear at the end;
hashes that don't fall into other buckets are mapped to its assigned value.

Example:

```nginx
split_clients "${remote_addr}AAA" $variant {
               0.5%               .one;
               2.0%               .two;
               *                  "";
}
```

Here, after substitution in the `$*remote_addr*AAA` string,
the hash values are distributed as follows:

- values from 0 to 21474835 (0.5%) yield `.one`
- values from 21474836 to 107374180 (2%) yield `.two`
- values from 107374181 to 4294967295 (all others) yield `""`
  (an empty string)


# https://en.angie.software/angie/docs/configuration/modules/stream/stream_ssl.md






# SSL

Provides the necessary support for a stream proxy server to work with the SSL/TLS protocol.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module isn't built
by default; it must be enabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--with-stream_ssl_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.

#### NOTE
This module requires the OpenSSL library.



## Configuration Example

To reduce the processor load it is recommended to

* set the number of [worker processes](https://en.angie.software//angie/docs/configuration/modules/core.md#worker-processes) equal to the number of processors,
* enable the [shared](#s-ssl-session-cache) session cache,
* disable the [built-in](#s-ssl-session-cache) session cache,
* and possibly increase the session [lifetime](#s-ssl-session-timeout) (by default, 5 minutes):

```nginx
worker_processes auto;

stream {

    #...

    server {
        listen              12345 ssl;

        ssl_protocols       TLSv1.2 TLSv1.3;
        ssl_ciphers         AES128-SHA:AES256-SHA:RC4-SHA:DES-CBC3-SHA:RC4-MD5;
        ssl_certificate     /usr/local/angie/conf/cert.pem;
        ssl_certificate_key /usr/local/angie/conf/cert.key;
        ssl_session_cache   shared:SSL:10m;
        ssl_session_timeout 10m;

    #    ...
    }
```



## Directives





### ssl_alpn

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_alpn` protocol ...;   |
|------------------------------------------------------------------------------------------|----------------------------|
| Default                                                                                  | —                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server             |

Specifies the list of supported [ALPN](https://datatracker.ietf.org/doc/html/rfc7301) protocols. One of the protocols must be [negotiated](#v-s-ssl-alpn-protocol) if the client uses ALPN:

```nginx
map $ssl_alpn_protocol $proxy {
    h2                 127.0.0.1:8001;
    http/1.1           127.0.0.1:8002;
}

server {
    listen      12346;
    proxy_pass  $proxy;
    ssl_alpn    h2 http/1.1;
}
```





### ssl_certificate

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_certificate` file;   |
|------------------------------------------------------------------------------------------|---------------------------|
| Default                                                                                  | —                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server            |

Specifies a file with the certificate in the PEM format for the given server. If intermediate certificates should be specified in addition to a primary certificate, they should be specified in the same file in the following order: the primary certificate comes first, then the intermediate certificates. A secret key in the PEM format may be placed in the same file.

This directive can be specified multiple times to load certificates of different types, for example, RSA and ECDSA:

```nginx
server {
    listen              12345 ssl;

    ssl_certificate     example.com.rsa.crt;
    ssl_certificate_key example.com.rsa.key;

    ssl_certificate     example.com.ecdsa.crt;
    ssl_certificate_key example.com.ecdsa.key;

#    ...
}
```

Only OpenSSL 1.0.2 or higher supports separate certificate chains for different certificates. With older versions, only one certificate chain can be used.

#### NOTE
The file name can contain [variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables) when using OpenSSL 1.0.2 or higher:

```nginx
ssl_certificate     $ssl_server_name.crt;
ssl_certificate_key $ssl_server_name.key;
```

Note that using variables implies that a certificate will be loaded for each SSL handshake, and this may have a negative impact on performance.

The value `data:`$variable`` can be specified instead of the `file`, which loads a certificate from a variable without using intermediate files.

Note that inappropriate use of this syntax may have its security implications, such as writing secret key data to [error log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log).





### ssl_certificate_cache

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_certificate_cache` `off`;

`ssl_certificate_cache` `max=`N [`inactive=`time] [`valid=`time];   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `ssl_certificate_cache off;`                                                                                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                                                                                              |

Defines a cache that stores [SSL certificates](#s-ssl-certificate) and [secret keys](#s-ssl-certificate-key) specified using variables.

The directive supports the following parameters:

- `max` — sets the maximum number of elements in the cache. When the cache
  overflows, the least recently used (LRU) elements are removed.
- `inactive` — defines the time after which an element is removed if it
  has not been accessed during this time, even if still within its
  `valid` period; each access resets this timer. The default is 10
  seconds.
- `valid` — defines the time during which a cached element is considered
  valid and can be reused. The default is 60 seconds. After this period,
  certificates are reloaded or revalidated.
- `off` — disables the cache.

Example:

```nginx
ssl_certificate       $ssl_server_name.crt;
ssl_certificate_key   $ssl_server_name.key;
ssl_certificate_cache max=1000 inactive=20s valid=1m;
```





### ssl_certificate_compression

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_certificate_compression` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-----------------------------------------------|
| Default                                                                                  | `ssl_certificate_compression off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                                |

Enables TLS 1.3 [compression](https://datatracker.ietf.org/doc/html/rfc8879) of server certificates.

#### NOTE
The directive is supported when using OpenSSL 3.2 or higher; the list of supported compression algorithms is provided by the library.

#### NOTE
The directive is supported when using [BoringSSL](https://boringssl.googlesource.com/boringssl/); the list of supported compression algorithms includes `zlib`.

If [ssl_stapling](#s-ssl-stapling) is enabled, certificate compression is disabled.





### ssl_certificate_key

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_certificate_key` file;   |
|------------------------------------------------------------------------------------------|-------------------------------|
| Default                                                                                  | —                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                |

Specifies a file with the secret key in the PEM format for the given server.

#### NOTE
The file name can contain variables when using OpenSSL 1.0.2 or higher.

The value `engine:`name`:id` can be specified instead of the `file`, which loads a secret key with a specified id from the OpenSSL engine name.

The value `store:scheme:id` can be specified instead of the `file`, which is used to load a secret key with a specified id and OpenSSL provider registered URI scheme, such as [pkcs11](https://datatracker.ietf.org/doc/html/rfc7512).

The value `data:`$variable`` can be specified instead of the `file`, which loads a secret key from a variable without using intermediate files. Note that inappropriate use of this syntax may have its security implications, such as writing secret key data to [error log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log).





### ssl_ciphers

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ciphers` ciphers;          |
|------------------------------------------------------------------------------------------|---------------------------------|
| Default                                                                                  | `ssl_ciphers HIGH:!aNULL:!MD5;` |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                  |

Specifies the enabled ciphers. The ciphers are specified in the format understood by the OpenSSL library, for example:

```nginx
ssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;
```

The list of ciphers depends on the version of OpenSSL installed.
The full list can be viewed using the `openssl ciphers` command.

#### WARNING
The `ssl_ciphers` directive does *not* configure ciphers for TLS
1.3 when using OpenSSL. To configure TLS 1.3 ciphers with OpenSSL, use the
[ssl_conf_command](#s-ssl-conf-command) directive, which was added to support advanced
SSL configuration.

- In LibreSSL, TLS 1.3 ciphers *can* be configured using
  `ssl_ciphers`.
- In BoringSSL, TLS 1.3 ciphers cannot be configured at all.





### ssl_client_certificate

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_client_certificate` file;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | —                                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                   |

Specifies a file with trusted CA certificates in the PEM format used to
[verify](#s-ssl-verify-client) client certificates and OCSP responses if
[ssl_stapling](#s-ssl-stapling) is enabled.

The list of certificates will be sent to clients. If this is not desired, the [ssl_trusted_certificate](#s-ssl-trusted-certificate) directive can be used.





### ssl_conf_command

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_conf_command` name value;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | —                                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                   |

Sets arbitrary OpenSSL configuration [commands](https://docs.openssl.org/master/man3/SSL_CONF_cmd/).

#### NOTE
The directive is supported when using OpenSSL 1.0.2 or higher.
To configure TLS 1.3 ciphers with OpenSSL, use the `ciphersuites` command.

Several ssl_conf_command directives can be specified on the same level:

```nginx
ssl_conf_command Options PrioritizeChaCha;
ssl_conf_command Ciphersuites TLS_CHACHA20_POLY1305_SHA256;
```

These directives are inherited from the previous configuration level if and only if there are no ssl_conf_command directives defined on the current level.

#### WARNING
Configuring OpenSSL directly might result in unexpected behavior.





### ssl_crl

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_crl` file;   |
|------------------------------------------------------------------------------------------|-------------------|
| Default                                                                                  | —                 |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server    |

Specifies a file with revoked certificates (CRL) in the PEM format used to [verify](#s-ssl-verify-client) client certificates.





### ssl_dhparam

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_dhparam` file;   |
|------------------------------------------------------------------------------------------|-----------------------|
| Default                                                                                  | —                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server        |

Specifies a file with DH parameters for DHE ciphers.

#### WARNING
By default no parameters are set, and therefore DHE ciphers will not be used.





### ssl_early_data

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_early_data` `on` | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | `ssl_early_data off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                   |

Enables or disables TLS 1.3 [early data](https://datatracker.ietf.org/doc/html/rfc8446#section-2.3).

#### NOTE
The directive is supported when using OpenSSL 1.1.1 or higher or [BoringSSL](https://boringssl.googlesource.com/boringssl/).





### ssl_ecdh_curve

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ecdh_curve` curve;   |
|------------------------------------------------------------------------------------------|---------------------------|
| Default                                                                                  | `ssl_ecdh_curve auto;`    |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server            |

Specifies a curve for ECDHE ciphers.

#### NOTE
When using OpenSSL 1.0.2 or higher, it is possible to specify multiple curves, for example:

```nginx
ssl_ecdh_curve prime256v1:secp384r1;
```

The special value `auto` instructs Angie to use a list built into the OpenSSL library when using OpenSSL 1.0.2 or higher, or prime256v1 with older versions.

#### NOTE
When using OpenSSL 1.0.2 or higher, this directive sets the list of curves supported by the server. Thus, in order for ECDSA certificates to work, it is important to include the curves used in the certificates.





### ssl_encrypted_hello_key

#### Versionadded
Added in version 1.11.0.

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_encrypted_hello_key` file;   |
|------------------------------------------------------------------------------------------|-----------------------------------|
| Default                                                                                  | —                                 |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                    |

Specifies a file with an ECH private key and ECHConfigList in PEM format.
The directive can be specified multiple times.
Requires an OpenSSL or BoringSSL build with Encrypted Client Hello (ECH)
support; otherwise it is not supported.





### ssl_handshake_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_handshake_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `ssl_handshake_timeout 60s;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                                                                                                         |

Specifies a timeout for the SSL handshake to complete.





### ssl_keylog_file

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_keylog_file` file;   |
|------------------------------------------------------------------------------------------|---------------------------|
| Default                                                                                  | —                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server            |

Specifies a file to log SSL/TLS keys for connections handled by the context,
using the [SSLKEYLOGFILE](https://www.ietf.org/archive/id/draft-thomson-tls-keylogfile-00.html)
format used by tools such as Wireshark to decrypt captured TLS traffic.

The directive should not be used with LibreSSL.

#### WARNING
The file contains sensitive TLS key material that can decrypt captured
traffic for the corresponding connections. Use this directive only for
debugging or protocol analysis, restrict access to the file, and remove it
when no longer needed.





### ssl_ntls

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ntls` `on` | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------|
| Default                                                                                  | `ssl_ntls off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server             |

Enables server-side support for NTLS using [TongSuo](https://github.com/Tongsuo-Project/Tongsuo) library.

```nginx
listen ... ssl;
ssl_ntls  on;
```

#### NOTE
Angie must be built using the `--with-ntls` build option and linked with NTLS-enabled SSL library

```default
./configure --with-openssl=../Tongsuo-8.3.0 \
            --with-openssl-opt=enable-ntls  \
            --with-ntls
```





### ssl_ocsp

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ocsp` `on` | `off` | `leaf`;   |
|------------------------------------------------------------------------------------------|-------------------------------------|
| Default                                                                                  | `ssl_ocsp off;`                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                      |

Enables OCSP validation of the client certificate chain. The `leaf`
parameter enables validation of the client certificate only.

For the OCSP validation to work, the [ssl_verify_client](#s-ssl-verify-client) directive should
be set to `on` or `optional`.

To resolve the OCSP responder hostname, the [resolver](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#s-resolver) directive should
also be specified.

Example:

```nginx
ssl_verify_client on;
ssl_ocsp          on;
resolver          127.0.0.53;
```





### ssl_ocsp_cache

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ocsp_cache` `off` | [shared:name:size];   |
|------------------------------------------------------------------------------------------|------------------------------------------------|
| Default                                                                                  | `ssl_ocsp_cache off;`                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                                 |

Sets name and size of the cache that stores client certificates status for OCSP
validation. The cache is shared between all worker processes. A cache with the
same name can be used in several virtual servers.

The `off` parameter prohibits the use of the cache.





### ssl_ocsp_responder

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ocsp_responder` uri;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| Default                                                                                  | —                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server              |

Overrides the URI of the OCSP responder specified in the ["Authority Information
Access"](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.2.1)
certificate extension for [validation](#s-ssl-ocsp) of client certificates.

Only `http://` OCSP responders are supported:

```nginx
ssl_ocsp_responder http://ocsp.example.com/;
```





### ssl_password_file

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_password_file` file;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| Default                                                                                  | —                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server              |

Specifies a file with passphrases for [secret keys](#s-ssl-certificate-key) where each passphrase is specified on a separate line. Passphrases are tried in turn when loading the key.

Example:

```nginx
stream {
    ssl_password_file /etc/keys/global.pass;
    ...

    server {
        listen 127.0.0.1:12345;
        ssl_certificate_key /etc/keys/first.key;
    }

    server {
        listen 127.0.0.1:12346;

        # named pipe can also be used instead of a file
        ssl_password_file /etc/keys/fifo;
        ssl_certificate_key /etc/keys/second.key;
    }
}
```





### ssl_prefer_server_ciphers

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_prefer_server_ciphers` `on` | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| Default                                                                                  | `ssl_prefer_server_ciphers off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                              |

Specifies that server ciphers should be preferred over client ciphers when the SSLv3 and TLS protocols are used.





### ssl_protocols

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_protocols` [`SSLv2`] [`SSLv3`] [`TLSv1`] [`TLSv1.1`] [`TLSv1.2`] [`TLSv1.3`];   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
| Default                                                                                  | `ssl_protocols TLSv1.2 TLSv1.3;`                                                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                                                                       |

Enables the specified protocols.

#### NOTE
The TLSv1.1 and TLSv1.2 parameters work only when OpenSSL 1.0.1 or higher is used.

The TLSv1.3 parameter works only when OpenSSL 1.1.1 or higher is used.





### ssl_session_cache

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_session_cache` `off` | `none` | [builtin[:size]] [shared:name:size];   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| Default                                                                                  | `ssl_session_cache none;`                                                   |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                                                              |

Sets the types and sizes of caches that store session parameters. A cache can be of any of the following types:

| `off`     | the use of a session cache is strictly prohibited: Angie explicitly tells a client that sessions may not be reused.                                                                                                                                                                                                                                                                                                                                |
|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `none`    | the use of a session cache is gently disallowed: Angie tells a client that sessions may be reused, but does not actually store session parameters in the cache.                                                                                                                                                                                                                                                                                    |
| `builtin` | a cache built in OpenSSL; used by one worker process only. The cache size is specified in sessions. If size is not given, it is equal to 20480 sessions. Use of the built-in cache can cause memory fragmentation.                                                                                                                                                                                                                                 |
| `shared`  | a cache shared between all worker processes. The cache size is specified in bytes; one megabyte can store about 4000 sessions. Each shared cache should have an arbitrary name. A cache with the same name can be used in several servers. It is also used to automatically generate, store, and periodically rotate TLS session ticket keys unless configured explicitly using the [ssl_session_ticket_key](#s-ssl-session-ticket-key) directive. |

Both cache types can be used simultaneously, for example:

```nginx
ssl_session_cache builtin:1000 shared:SSL:10m;
```

but using only shared cache without the built-in cache should be more efficient.





### ssl_session_ticket_key

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_session_ticket_key` file;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | —                                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                   |

Sets a file with the secret key used to encrypt and decrypt TLS session tickets. The directive is necessary if the same key has to be shared between multiple servers. By default, a randomly generated key is used.

If several keys are specified, only the first key is used to encrypt TLS session tickets. This allows configuring key rotation, for example:

```nginx
ssl_session_ticket_key current.key;
ssl_session_ticket_key previous.key;
```

The file must contain 80 or 48 bytes of random data and can be created using the following command:

```console
$ openssl rand 80 > ticket.key
```

Depending on the file size, either AES256 (for 80-byte keys) or AES128 (for 48-byte keys) will be used for encryption.





### ssl_session_tickets

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_session_tickets` `on` | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------------|
| Default                                                                                  | `ssl_session_tickets on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                        |

Enables or disables session resumption through [TLS session tickets](https://datatracker.ietf.org/doc/html/rfc5077).





### ssl_session_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_session_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `ssl_session_timeout 5m;`                                                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                                                                                                       |

Specifies a time during which a client may reuse the session parameters.





### ssl_stapling

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_stapling` `on` | `off`;   |
|------------------------------------------------------------------------------------------|--------------------------------|
| Default                                                                                  | `ssl_stapling off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                   |

Enables or disables [stapling of OCSP responses](https://datatracker.ietf.org/doc/html/rfc6066#section-8) by the server.
Example:

```nginx
ssl_stapling on;
resolver 127.0.0.53;
```

For the OCSP stapling to work, the certificate of the server certificate issuer
should be known. If the [ssl_certificate](#s-ssl-certificate) file does not contain
intermediate certificates, the certificate of the server certificate issuer
should be present in the [ssl_trusted_certificate](#s-ssl-trusted-certificate) file.

#### WARNING
For the resolution of the OCSP responder hostname, the [resolver](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#s-resolver)
directive should also be specified.





### ssl_stapling_file

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_stapling_file` file;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| Default                                                                                  | —                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                |

When set, the stapled OCSP response will be taken from the specified file
instead of querying the OCSP responder specified in the server certificate.

The file should be in the DER format as produced by the `openssl ocsp`
command.





### ssl_stapling_responder

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_stapling_responder` uri;   |
|------------------------------------------------------------------------------------------|---------------------------------|
| Default                                                                                  | —                               |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                    |

Overrides the URI of the OCSP responder specified in the ["Authority Information
Access"](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.2.1)
certificate extension.

Only `http://` OCSP responders are supported:

```nginx
ssl_stapling_responder http://ocsp.example.com/;
```





### ssl_stapling_verify

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_stapling_verify` `on` | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------------|
| Default                                                                                  | `ssl_stapling_verify off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                          |

Enables or disables verification of OCSP responses by the server.

For verification to work, the certificate of the server certificate issuer, the root certificate, and all intermediate certificates should be configured as trusted using the [ssl_trusted_certificate](#s-ssl-trusted-certificate) directive.





### ssl_trusted_certificate

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_trusted_certificate` file;   |
|------------------------------------------------------------------------------------------|-----------------------------------|
| Default                                                                                  | —                                 |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                    |

Specifies a file with trusted CA certificates in the PEM format used to [verify](#s-ssl-verify-client) client certificates.

In contrast to the certificate set by [ssl_client_certificate](#s-ssl-client-certificate), the list of these certificates will not be sent to clients.





### ssl_verify_client

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_verify_client` `on` | `off` | `optional` | `optional_no_ca`;   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
| Default                                                                                  | `ssl_verify_client off;`                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                                                      |

Enables verification of client certificates. The verification result is stored in the [$ssl_client_verify](#v-s-ssl-client-verify) variable. If an error has occurred during the client certificate verification or a client has not presented the required certificate, the connection is closed.

| `optional`       | requests the client certificate and verifies it if the certificate is present.                                                                                                                                             |
|------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `optional_no_ca` | requests the client certificate but does not require it to be signed by a trusted CA certificate. This is intended for use in cases when a service that is external to Angie performs the actual certificate verification. |





### ssl_verify_depth

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_verify_depth` number;   |
|------------------------------------------------------------------------------------------|------------------------------|
| Default                                                                                  | `ssl_verify_depth 1;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server               |

Sets the verification depth in the client certificates chain.



## Built-in Variables

The `stream_ssl` module supports the following variables:



### `$ssl_alpn_protocol`

returns the protocol selected by ALPN during the SSL handshake, or an empty string otherwise.



### `$ssl_cipher`

returns the name of the cipher used for an established SSL connection.



### `$ssl_ciphers`

returns the list of ciphers supported by the client. Known ciphers are listed by names, unknown are shown in hexadecimal, for example:

> AES128-SHA:AES256-SHA:0x00ff

#### NOTE
The variable is fully supported only when using OpenSSL version 1.0.2 or higher. With older versions, the variable is available only for new sessions and lists only known ciphers.



### `$ssl_client_cert`

returns the client certificate in the PEM format for an established SSL connection, with each line except the first prepended with the tab character.



### `$ssl_client_fingerprint`

returns the SHA1 fingerprint of the client certificate for an established SSL connection.



### `$ssl_client_i_dn`

returns the "issuer DN" string of the client certificate for an established SSL connection according to [RFC 2253](https://datatracker.ietf.org/doc/html/rfc2253).



### `$ssl_client_raw_cert`

returns the client certificate in the PEM format for an established SSL connection.



### `$ssl_client_s_dn`

returns the "subject DN" string of the client certificate for an established SSL connection according to [RFC 2253](https://datatracker.ietf.org/doc/html/rfc2253).



### `$ssl_client_serial`

returns the serial number of the client certificate for an established SSL connection.



### `$ssl_client_sigalg`

returns the [signature algorithm](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-16) for the client certificate for an established SSL connection.

#### NOTE
The variable is supported only when using OpenSSL version 3.5 or higher. With older versions, the variable value will be an empty string.

#### NOTE
The variable is available only for new sessions.



### `$ssl_client_v_end`

returns the end date of the client certificate.



### `$ssl_client_v_remain`

returns the number of days until the client certificate expires.



### `$ssl_client_v_start`

returns the start date of the client certificate.



### `$ssl_client_verify`

returns the result of client certificate verification: `SUCCESS`, `FAILED:reason`, and `NONE` if a certificate was not present.



### `$ssl_curve`

returns the negotiated curve used for SSL handshake key exchange process. Known curves are listed by names, unknown are shown in hexadecimal, for example:

> prime256v1

#### NOTE
The variable is supported only when using OpenSSL version 3.0 or higher. With older versions, the variable value will be an empty string.



### `$ssl_curves`

returns the list of curves supported by the client. Known curves are listed by names, unknown are shown in hexadecimal, for example:

> 0x001d:prime256v1:secp521r1:secp384r1

#### NOTE
The variable is supported only when using OpenSSL version 1.0.2 or higher. With older versions, the variable value will be an empty string.

The variable is available only for new sessions.



### `$ssl_early_data`

returns "1" if TLS 1.3 [early data](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-early-data) is used and the handshake is not complete, otherwise "".



### `$ssl_encrypted_hello`

#### Versionadded
Added in version 1.11.0.

returns "1" if Encrypted Client Hello (ECH) is used, otherwise "".



### `$ssl_protocol`

returns the protocol of an established SSL connection.



### `$ssl_server_cert_type`

takes the values `RSA`, `DSA`, `ECDSA`, `ED448`,
`ED25519`, `SM2`, `RSA-PSS`, or `unknown` depending
on the type of server certificate and key.



### `$ssl_server_name`

returns the server name requested through [SNI](http://en.wikipedia.org/wiki/Server_Name_Indication).



### `$ssl_session_id`

returns the session identifier of an established SSL connection.



### `$ssl_session_reused`

returns "r" if an SSL session was reused, or "." otherwise.



### `$ssl_sigalg`

returns the [signature algorithm](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-16) for the server certificate for an established SSL connection.

#### NOTE
The variable is supported only when using OpenSSL version 3.5 or higher. With older versions, the variable value will be an empty string.

#### NOTE
The variable is available only for new sessions.



### `$ssl_sigalgs`

returns the list of [signature algorithms](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-16) offered by the client during the SSL handshake, as a colon-separated list.

#### NOTE
With OpenSSL version 4.0 or higher, algorithms are returned by name; an
algorithm without a name falls back to its raw hexadecimal code. SSL
libraries that expose the older signature-algorithm API return all
algorithms as raw hexadecimal codes. Builds without a supported
signature-algorithm API return an empty value.


# https://en.angie.software/angie/docs/configuration/modules/stream/stream_ssl_preread.md





# SSL Preread

Enables extracting information from the
[ClientHello](https://datatracker.ietf.org/doc/html/rfc5246#section-7.4.1.2)
message without terminating TLS,
such as the server name requested via
[SNI](https://datatracker.ietf.org/doc/html/rfc6066#section-3)
or protocols advertised in
[ALPN](https://datatracker.ietf.org/doc/html/rfc7301).

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module isn't built
by default; it must be enabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--with-stream_ssl_preread_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example



### Selecting an upstream by server name

```nginx
map $ssl_preread_server_name $name {
    backend.example.com      backend;
    default                  backend2;
}

upstream backend {
    server 192.168.0.1:12345;
    server 192.168.0.2:12345;
}

upstream backend2 {
    server 192.168.0.3:12345;
    server 192.168.0.4:12345;
}

server {
    listen      12346;
    proxy_pass  $name;
    ssl_preread on;
}
```



### Selecting a server by protocol

```nginx
map $ssl_preread_alpn_protocols $proxy {
    ~\bh2\b           127.0.0.1:8001;
    ~\bhttp/1.1\b     127.0.0.1:8002;
    ~\bxmpp-client\b  127.0.0.1:8003;
}

server {
    listen      9000;
    proxy_pass  $proxy;
    ssl_preread on;
}
```



### Selecting a server by SSL protocol version

```nginx
map $ssl_preread_protocol $upstream {
    ""        ssh.example.com:22;
    "TLSv1.2" new.example.com:443;
    default   tls.example.com:443;
}

# ssh and https at the same port
server {
    listen      192.168.0.1:443;
    proxy_pass  $upstream;
    ssl_preread on;
}
```



## Directives





### ssl_preread

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_preread` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-------------------------------|
| Default                                                                                  | `ssl_preread off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                |

Enables extracting information from the ClientHello message at the
[preread](https://en.angie.software//angie/docs/configuration/processing.md#stream-sessions) phase.



## Built-in Variables



### `$ssl_preread_alpn_protocols`

List of protocols advertised by the client through ALPN.
The values are comma separated.



### `$ssl_preread_protocol`

Highest SSL protocol version supported by the client.



### `$ssl_preread_server_name`

Server name requested via SNI.


# https://en.angie.software/angie/docs/configuration/modules/stream/stream_upstream.md








# Upstream

Provides context for describing groups of servers that can be used in the [proxy_pass](https://en.angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-pass) directive.



## Configuration Example

```nginx
upstream backend {
    hash $remote_addr consistent;
    zone backend 1m;

    server backend1.example.com:1935  weight=5;
    server unix:/tmp/backend3;
    server backend3.example.com       service=_example._tcp resolve;

    server backup1.example.com:1935   backup;
    server backup2.example.com:1935   backup;
}

resolver 127.0.0.53 status_zone=resolver;

server {
    listen 1936;
    proxy_pass backend;
}
```



## Directives





### backup_switch (PRO)

#### Versionadded
Added in version 1.10.0: PRO

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `backup_switch` `permanent`[=time];   |
|------------------------------------------------------------------------------------------|---------------------------------------|
| Default                                                                                  | —                                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                              |

The directive enables the ability to start server selection not from the primary group,
but from the *active* group, i.e., the one where a server was successfully found previously.
If a server cannot be found in the active group for the next request,
and the search moves to the backup group,
this backup group becomes active,
and subsequent requests are first directed to servers in this group.

If the `permanent` parameter is defined without a [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units) value,
the group remains active after selection,
and automatic re-checking of groups with lower priority levels does not occur.
If time is specified,
the active status of the group expires after the specified interval,
and the load balancer again checks groups with lower priority levels,
returning to them if the servers are working normally.

Example:

```nginx
upstream media_backend {
    zone media_backend 1m;
    server primary1.example.com:1935;
    server primary2.example.com:1935;

    server reserve1.example.com:1935 backup;
    server reserve2.example.com:1935 backup;

    backup_switch permanent=2m;
}
```

If the load balancer switches from primary servers to the backup group,
all subsequent requests are handled by this backup group for 2 minutes.
After 2 minutes expire, the load balancer re-checks the primary servers
and makes them active again if they are working normally.





### feedback (PRO)

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `feedback` variable [`inverse`] [`factor=`number] [`account=`condition_variable];   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------|
| Default                                                                                  | —                                                                                   |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                                                                            |

Enables a feedback-based load balancing mechanism for the `upstream`.
It dynamically adjusts load balancing decisions
by multiplying each proxied server's weight by the average feedback value,
which changes over time based on the variable value
and is subject to an optional condition.

The following parameters can be specified:

| `variable`   | The variable from which the feedback value is taken.
It should represent a performance or health metric;
it is assumed to be provided by the server.

The value is evaluated with each response from the server
and factored into the moving average
according to `inverse` and `factor` settings.                                                                                                                                                                                                                                                                                                                                                                    |
|--------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `inverse`    | If the parameter is set, the feedback value is interpreted inversely:
lower values indicate better performance.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `factor`     | The factor by which the feedback value is weighted
when calculating the average.
Valid values are integers from 0 to 99.
Default is `90`.

The average is calculated using the [exponential smoothing](https://en.wikipedia.org/wiki/Exponential_smoothing) formula.

The larger the factor, the less new values affect the average;
if `90` is specified, 90% of the previous value will be taken
and only 10% of the new value.                                                                                                                                                                                                                         |
| `account`    | Specifies a condition variable
that controls how connections are accounted for in the calculation.
The average value is updated with the feedback value
only if the condition variable
is not equal to `""` or `"0"`.

#### NOTE
By default, traffic from [probes](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe)
is not included in the calculation;
combining the [$upstream_probe](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#v-upstream-probe) variable
with `account` allows including them
or even excluding everything else. |

Example:

```nginx
upstream backend {

    zone backend 1m;

    feedback $feedback_value factor=80 account=$condition_value;

    server backend1.example.com:1935  weight=1;
    server backend2.example.com:1935  weight=2;
}

map $protocol $feedback_value {
    "TCP"                      100;
    "UDP"                      75;
    default                    10;
}

map $upstream_probe $condition_value {
    "high_priority" "1";
    "low_priority"  "0";
    default         "1";
}
```

This configuration categorizes servers by feedback levels
based on protocols used in individual sessions,
and also adds a condition on [$upstream_probe](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#v-upstream-probe)
to account only for `high_priority` probes
or regular client sessions.





### hash

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `hash` key [`consistent`];   |
|------------------------------------------------------------------------------------------|------------------------------|
| Default                                                                                  | —                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                     |

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), support for this
directive can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-stream_upstream_hash_module`.

Specifies a load balancing method for the group where client-server mapping is determined using a hashed key value. The key can contain [variables](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables). Note that any addition or removal of servers from the group may result in remapping of most keys to different servers. The method is compatible with the Perl [Cache::Memcached](https://metacpan.org/pod/Cache::Memcached) library.

Usage example:

```nginx
hash $remote_addr;
```

When using domain names that resolve to multiple IP addresses
(for example, with the `resolve` parameter),
the server does not sort the received addresses, so their order may differ
across different servers, which affects client distribution.
To ensure consistent distribution,
use the `consistent` parameter.

If the `consistent` parameter is specified, the ketama consistent hashing method will be used instead of the above method. The method ensures that when a server is added to or removed from the group, only a minimal number of keys will be remapped to other servers. Using the method for caching servers provides a higher cache hit ratio. The method is compatible with the Perl [Cache::Memcached::Fast](https://metacpan.org/pod/Cache::Memcached::Fast) library with the `ketama_points` parameter set to 160.





### least_conn

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `least_conn`;   |
|------------------------------------------------------------------------------------------|-----------------|
| Default                                                                                  | —               |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream        |

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), support for this
directive can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-stream_upstream_least_conn_module`.

Specifies a load balancing method for the group where a connection is passed to the server with the least number of active connections, taking into account server weights. If several servers are suitable, they are selected cyclically (round-robin) with their weights taken into account.





### least_time

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `least_time` `connect` | `first_byte` | `last_byte` [`factor=`number] [`account=`condition_variable];   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| Default                                                                                  | —                                                                                                       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                                                                                                |

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), support for this
directive can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-stream_upstream_least_time_module`.

Specifies a load balancing method for the group where the probability of passing
a connection to an active server is inversely proportional to its average
response time; the lower it is, the more connections the server will receive.

| `connect`    | The directive takes into account the average time to establish a connection.   |
|--------------|--------------------------------------------------------------------------------|
| `first_byte` | The directive uses the average time to receive the first byte of the response. |
| `last_byte`  | The directive uses the average time to receive the full response.              |

| `factor`   | Performs the same function as [response_time_factor](#s-u-response-time-factor),
and overrides it if the parameter is specified.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `account`  | Specifies a condition variable
that controls which connections are accounted for in the calculation.
The average value is updated
only if the connection's condition variable
is not equal to `""` or `"0"`.

#### NOTE
By default, [probes (PRO)](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe)
are not included in the calculation;
combining the [$upstream_probe](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#v-upstream-probe) variable
with `account` allows including them
or even excluding everything else. |

Current values are presented as `connect_time`, `first_byte_time`,
and `last_byte_time` in the server's `health` object
among [upstream metrics](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-stream-upstreams) in the API.





### no_port (PRO)

#### Versionadded
Added in version 1.12.0: PRO

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `no_port`;   |
|------------------------------------------------------------------------------------------|--------------|
| Default                                                                                  | —            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream     |

Explicitly marks the server group as portless: its [server](#s-u-server)
addresses are specified without a port, and the connect port is instead supplied
by each [proxy_pass](https://en.angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-pass) directive that references the group.

The directive is intended for groups that list no servers statically and are
instead populated dynamically through the [configuration API](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-config-stream-upstreams-servers). Such groups require a [shared
memory zone](#s-u-zone) and by default are treated as requiring ports. A single
portless group can then be reused for proxying to different ports without
duplicating the server list:

```nginx
upstream backend {
    zone backend 1m;
    no_port;
}

server {
    listen 8443;
    proxy_pass backend:8443;
}

server {
    listen 8080;
    proxy_pass backend:8080;
}
```

A group is also treated as portless without this directive
when its [server](#s-u-server) addresses
are domain names or IP addresses without ports.
The `no_port` directive states this property explicitly
and rejects addresses that include a port.

A portless group accepts only domain names and IP addresses without ports;
UNIX domain socket addresses and servers that use the `service=`
parameter for DNS SRV resolution are not allowed.
Domain names and IP addresses in one group must either all include ports
or all omit them; mixed port usage is not allowed.





### random

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `random` [`two`];   |
|------------------------------------------------------------------------------------------|---------------------|
| Default                                                                                  | —                   |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream            |

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), support for this
directive can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-stream_upstream_random_module`.

Specifies a load balancing method for the group where a connection is passed to a randomly selected server, taking into account server weights.

If the optional `two` parameter is specified, Angie randomly selects two servers and then chooses a server using the specified method. The default method is [least_conn](#s-u-least-conn), which passes the connection to the server with the least number of active connections.





### response_time_factor

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `response_time_factor` number;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | `response_time_factor 90;`       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                         |

Specifies for the [least_time](#s-u-least-time) load balancing method the smoothing
factor for the **previous** value when calculating the average response time using the
[exponentially weighted moving average](https://en.wikipedia.org/wiki/Moving_average#Exponential_moving_average) formula.

The larger the specified number, the less new values affect the average; if
`90` is specified, 90% of the previous value will be taken and only 10% of
the new value. Valid values are from 0 to 99 inclusive.

Current calculation results are presented as `connect_time` (time
to establish a connection), `first_byte_time` (time to receive the first
byte of the response), and `last_byte_time` (time to receive the full response) in
the server's `health` object among [upstream metrics](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-stream-upstreams) in the API.

#### NOTE
Only successful responses are considered in the calculation;
what constitutes an unsuccessful response
is determined by the [proxy_next_upstream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-next-upstream) directives.





### server

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `server` address [parameters];   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | —                                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                         |

Defines the address and other parameters of a server. The address can be
specified as a domain name or IP address, or as a UNIX domain socket path
specified after the `unix:` prefix. A domain name that resolves to several
IP addresses defines multiple servers at once. For a domain name or IP address,
the port is required except in a [portless](#s-u-no-port) group (PRO),
where it is omitted and supplied by the [proxy_pass](https://en.angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-pass) directive instead.

The following parameters can be defined:

| `weight=`number    | Sets the weight of the server; by default, 1.                                                                                                                                                                                                             |
|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `max_conns=`number | Limits the maximum number of simultaneous active connections to the proxied server. Default value is `0`, meaning there is no limit. If the server group does not reside in the [shared memory](#s-u-zone), the limitation works per each worker process. |



`max_fails=`number — sets the number of unsuccessful attempts
to communicate with the server
that should happen in the duration set by [fail_timeout](#s-fail-timeout)
to consider the server unavailable;
it is then retried after the same duration.

Here, an unsuccessful attempt is an error or timeout while establishing a
connection with the server.

#### NOTE
If a `server` directive in a group resolves to multiple servers,
its `max_fails` setting applies to each server individually.

If an upstream contains only one server
after all its `server` directives are resolved,
the `max_fails` setting has no effect and will be ignored.

| `max_fails=1`   | The default number of attempts.      |
|-----------------|--------------------------------------|
| `max_fails=0`   | Disables the accounting of attempts. |



`fail_timeout=`time — sets the period of time during which a specified number of
unsuccessful attempts to communicate with the server ([max_fails](#s-max-fails)) should happen to consider the server unavailable.
The server then remains unavailable for the same amount of time
before it is retried.

By default, this is set to 10 seconds.

#### NOTE
If a `server` directive in a group resolves to multiple servers,
its `fail_timeout` setting applies to each server individually.

If an upstream contains only one server
after all its `server` directives are resolved,
the `fail_timeout` setting has no effect and will be ignored.

| `backup`   | Marks the server as a backup server. It will be passed requests when the primary servers are unavailable.                                                                                      |
|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `down`     | Marks the server as permanently unavailable.                                                                                                                                                   |
| `drain`    | Marks the server as draining; this means
it receives only requests from the sessions
that were bound earlier with [sticky](#s-u-sticky).
Otherwise it behaves similarly to `down`. |

#### WARNING
The `backup` parameter cannot be used along with the [hash](#s-u-hash) and [random](#s-u-random) load balancing methods.

The `down` and `drain` parameters are mutually exclusive.



| `resolve`      | Enables monitoring changes to the list of IP addresses that
corresponds to a domain name, updating it without a configuration reload.
The group must reside in a
[shared memory zone](#s-u-zone);
also, a [resolver](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#s-resolver) must be defined.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
|----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `service=`name | Enables resolving DNS SRV records and sets the service name.
For this parameter to work, the resolve parameter must also be specified,
without specifying the server port in the hostname.

If there are no dots in the service name,
the name is formed according to the RFC standard:
the service name is prefixed with `_`,
then `_tcp` is added after a dot.
Thus, the service name `http` will result in `_http._tcp`.

Angie resolves the SRV records
by combining the normalized service name and the hostname
and obtaining the list of servers for the combination via DNS,
along with their priorities and weights.

- Top-priority SRV records
  (ones that share the minimum priority value)
  resolve to primary servers,
  and other records become backup servers.
  If `backup` is set with `server`,
  top-priority SRV records resolve to backup servers,
  and other records are ignored.
- Weight is similar to the `weight` parameter of the `server` directive.
  If weight is set by both the directive and the SRV record,
  the weight set by the directive is used. |

This example will look up the `_http._tcp.backend.example.com` record:

```nginx
server backend.example.com service=http resolve;
```

| `sid=`id   | Sets the server ID in the group. If the parameter is not specified,
the ID is set as a hexadecimal MD5 hash
of the IP address and port or UNIX domain socket path.   |
|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|



| `slow_start=`time   | Sets the [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units) for a server to recover its weight
when returning to service
with [round-robin](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#round-robin) or [least_conn](#s-u-least-conn)
load balancing methods.

If the parameter is set
and a server is again considered healthy
after a failure according to [max_fails](#s-max-fails) and [upstream_probe (PRO)](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe),
the server gradually recovers its designated weight
over the specified time period.

If the parameter is not set,
in a similar situation
the server immediately starts working with its designated weight.   |
|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

#### NOTE
If only one `server` is specified in the upstream,
`slow_start` has no effect and will be ignored.





### state (PRO)

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `state` file;   |
|------------------------------------------------------------------------------------------|-----------------|
| Default                                                                                  | —               |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream        |

Specifies the file where the upstream server list is persistently stored.
When installing from
[our packages](https://en.angie.software//angie/docs/installation/index.md#install-packages),
a dedicated directory
`/var/lib/angie/state/` (`/var/db/angie/state/` on FreeBSD)
is created with appropriate permissions for storing such files,
so you only need to add the filename in the configuration:

```nginx
upstream backend {

    zone backend 1m;
    state /var/lib/angie/state/;
}
```

The server list format here is similar to `s_server`.
The file contents change whenever servers are modified in the
[/config/stream/upstreams/](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-config-stream-upstreams-servers) section
via the configuration API.
The file is read at Angie startup or configuration reload.

#### WARNING
To use the `state` directive in an `upstream` block,
there should be no `server` directives in it,
but a shared memory zone ([zone](#s-u-zone)) is required.





### sticky

#### Versionchanged
Changed in version 1.10.0: PRO

#### Versionchanged
Changed in version 1.11.0: PRO

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `sticky route` value...;

`sticky learn` `zone=`zone `create=`$create_var1... `lookup=`$lookup_var1... [`connect`] [`norefresh`] [`timeout=`time];

`sticky learn` `lookup=`$lookup_var1... `remote_action=`uri `remote_result=`$remote_var [`remote_uri=`uri]; (PRO)   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | —                                                                                                                                                                                                                                                                                       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                                                                                                                                                                                                                                                                                |

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), support for this
directive can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-stream_upstream_sticky_module`.

Configures sticky sessions between clients and upstream servers,
depending on the mode specified in the first parameter.
To gradually take servers with `sticky` out of rotation,
you can use the `drain` option in the [server](#s-u-server) block.

#### WARNING
The `sticky` directive must appear after all load balancing method directives,
otherwise it won't work.

`route` mode

This mode uses predefined route identifiers
that can be embedded in connection properties accessible to Angie.
It is less flexible as it depends on predefined values,
but is better suited if such identifiers are already in use.

Here, when establishing a connection, the upstream server
can assign a route to the client and return its identifier in a way
known to both parties.
The route identifier
should use the value of the [sid](#s-reresolve) parameter
of the [server](#s-u-server) directive.
Note that the parameter is additionally hashed
if the [sticky_secret](#s-u-sticky-secret) directive is specified.

Subsequent connections from clients wishing to use this route
must contain the identifier issued by the server, in such a way
that it ends up in Angie variables.

The directive parameters specify strings that may include variables
for routing. To select the server where the incoming connection is directed,
the first non-empty value is used;
it is then compared with the [sid](#s-reresolve) parameter
of the [server](#s-u-server) directive.
If server selection fails
or the selected server cannot accept the connection,
another server will be selected
according to the configured load balancing method.

Here Angie looks for the route identifier in the `$route` variable,
which receives its value based on [$ssl_preread_server_name](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl_preread.md#v-ssl-preread-server-name)
(note that [ssl_preread](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl_preread.md#s-ssl-preread) must be enabled):

```nginx
stream {

    map $ssl_preread_server_name $route {

        a.example.com            a;
        b.example.com            b;
        default                  "";
    }

    upstream backend {

        zone backend 1m;

        server 127.0.0.1:8081 sid=a;
        server 127.0.0.1:8082 sid=b;

        sticky route $route;
    }

    server {

        listen 127.0.0.1:8080;

        ssl_preread on;

        proxy_pass backend;
    }
}
```

`learn` mode

In this mode, a dynamically generated key is used
to bind a client to a specific upstream server;
this mode is more flexible
as it assigns servers on the fly,
stores sessions in a shared memory zone,
and supports various ways of passing session identifiers.

Here, a session is created
based on connection properties coming from the upstream server.
The `create` and `lookup` parameters list variables
that specify how new sessions are created and existing ones are found.
Both parameters can be used multiple times.

The session identifier is the value of the first non-empty variable
specified with `create`;
for example, this could be
the [upstream server name](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-server-name).

Sessions are stored in a shared memory zone;
its name and size are specified by the `zone` parameter.
If a session has not been accessed within the [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units)
specified by `timeout`, it is deleted.
The default value is 1 hour.

By default, Angie extends the session lifetime
by updating the last access timestamp each time it is used.
The `norefresh` parameter changes this behavior:
the session expires strictly by timeout, even if it is being used.

Subsequent connections from clients wishing to use a session
must contain its identifier.
The `lookup` parameter searches for the session identifier in the connection
using the specified list of variables,
stopping at the first non-empty one.
If nothing is found, the request is considered new.
The value of the found identifier
is matched against sessions in shared memory.
If server selection fails
or the selected server cannot handle the connection,
another server will be selected
according to the configured load balancing method.

The `connect` parameter allows creating a session
immediately after establishing a connection with the upstream server.
Without it, the session is created only after connection processing is complete.
(In the case of UDP connections, sessions are created immediately after server selection.)

In the example, Angie creates and looks up sessions
using the [$rdp_cookie](https://en.angie.software//angie/docs/configuration/modules/stream/stream_rdp_preread.md#v-rdp-cookie) variable:

```nginx
stream {

    upstream backend {

        zone backend 1m;

        server 127.0.0.1:3390;
        server 127.0.0.1:3391;

        sticky learn lookup=$rdp_cookie create=$rdp_cookie zone=sessions:1m;
    }

    server {

        listen 127.0.0.1:3389;

        rdp_preread on;

        proxy_pass backend;
    }
}
```

`learn` mode with `remote_action` (PRO 1.10.0+)

The `remote_action` and `remote_result` parameters
allow dynamically assigning and managing session identifiers
using a remote session store (PRO).

Unlike `learn` mode with `zone`,
this mode does not cache sessions locally
and queries the remote store for each connection.

The `remote_action` parameter must point to a `location`
in the [client](https://en.angie.software//angie/docs/configuration/modules/http/index.md#client) context.
The `remote_uri` parameter specifies the URI of the client HTTP request
to the specified `location`.
By default, it is `/`.
The `remote_uri` value can contain variables.

The general operating principle of this mode is as follows:
if a session identifier is not found locally,
Angie sends a synchronous subrequest to a remote store
specified by the `remote_action` parameter.

When a new connection arrives, Angie performs the following actions:

- First, the session identifier is extracted from the first non-empty variable
  in the `lookup` list.
  If all variables are empty,
  the normal load balancing algorithm is used without sticky sessions.
- Then Angie sends a synchronous HTTP subrequest to the remote store
  specified by the `remote_action` parameter, which should contain
  in a format understood by the store:
  - the *session* identifier from the `lookup` parameter
    (in the configuration, this is the
    [$sticky_sessid](#v-s-sticky-sessid) variable);
  - the identifier of the preselected *server*:
    the value of the `sid=` parameter from the `server` directive,
    if specified,
    or the MD5 hash of the server name
    (in the configuration, this is the
    [$sticky_sid](#v-s-sticky-sid) variable).

  The `$sticky_sessid` and `$sticky_sid` variables are automatically
  exported to the HTTP context with the `stream_` prefix:
  `$stream_sticky_sessid`, `$stream_sticky_sid`.
  This allows using them directly in HTTP directives,
  for example via HTTP headers using [proxy_set_header](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-set-header).
- The remote store processes the request and returns an HTTP response:

  A response with code 200, 201, or 204 confirms the selected server.
  The remote store can simultaneously
  return an alternative server identifier in an HTTP header or in the
  response body (PRO); it can be extracted via `remote_result`.

  When receiving any other HTTP code from the store
  (including network errors and timeouts)
  or a non-existent server identifier,
  Angie uses the originally selected server.

The server identifier is extracted from the remote store response
via the `remote_result` parameter:
it can specify variables
with the `upstream_http_` prefix,
which are created automatically by Angie to access
HTTP response headers from the remote store,
or [$sent_body](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-sent-body) to use the response body.
For example, the `X-Sid: server1` header in such a response
becomes accessible in the `$upstream_http_x_sid` variable
with the value `server1`.

Below is a simplified configuration example.
The remote store returns the server identifier in the `X-Sticky-Sid` header
and thus confirms or overrides Angie's selection:

```nginx
http {

    client {

        location @sticky_client1 {

            # use variables from the stream upstream;
            # it adds these variables to the HTTP context with the stream_* prefix
            proxy_set_header X-Sticky-Sessid $stream_sticky_sessid;
            proxy_set_header X-Sticky-Sid $stream_sticky_sid;
            proxy_set_header X-Sticky-Last $msec;
            proxy_pass http://127.0.0.1:8080;

            proxy_cache remote;
            proxy_cache_valid 200 1d;
            proxy_cache_key $scheme$proxy_host$request_uri$stream_sticky_sessid;
        }
    }
}

stream {

    upstream u {

        zone u 1m;

        server 127.0.0.1:8081 sid=backend-01;
        server 127.0.0.1:8082 sid=backend-02;

        sticky learn lookup=$remote_addr            # stream variable
        remote_action=@sticky_client1               # location from client block
        remote_result=$upstream_http_x_sticky_sid   # HTTP variable
        remote_uri=/foo;                            # default is /
    }

    server {

        listen 127.0.0.1:8080;
        proxy_pass u;
    }
}
```

Here, with the following response from the remote store:

```none
HTTP/1.1 200 OK
...
X-Sticky-Sid: backend-01
X-Session-Info: active
```

Two variables become available:

- `$upstream_http_x_sticky_sid`,
  with the value `backend-01`;
- `$upstream_http_x_session_info`,
  with the value `active`.

Since the `$upstream_http_x_sticky_sid` variable
is specified in the `remote_result` parameter,
its value will be used
to select the server with `sid=backend-01`.

The `sticky` directive takes into account the state of servers in [upstream](#s-u-upstream):

- Servers marked as `down` or temporarily unavailable due to failures
  are excluded from selection.
- Servers that have reached the maximum number of connections
  (when using `max_conns`) are temporarily skipped.
- Servers with the `drain` option
  can be selected for creating new sessions in `sticky` mode
  when identifiers match.
- If a previously unavailable server recovers,
  `sticky` automatically resumes using it.

The behavior of `sticky` can be further configured
with the [sticky_secret](#s-u-sticky-secret) and [sticky_strict](#s-u-sticky-strict) directives.
If `sticky` fails to select a server or it is unavailable,
the request will be handled according to the selected load balancing method,
unless the `sticky_strict` directive is enabled.
In `sticky_strict on;` mode, the request is rejected with an error.

Shared memory zones
specified in the `zone` parameter of the `sticky` directive
cannot be shared between different `upstream` groups;
each group must use its own zone.





### sticky_secret

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `sticky_secret` string;   |
|------------------------------------------------------------------------------------------|---------------------------|
| Default                                                                                  | —                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                  |

Adds string as salt to the MD5 hash function
for the [sticky](#s-u-sticky) directive in `route` mode.
String can contain variables, for example `$remote_addr`:

```nginx
upstream backend {
    zone backend 1m;
    server 127.0.0.1:8081 sid=a;
    server 127.0.0.1:8082 sid=b;

    sticky route $route;
    sticky_secret my_secret.$remote_addr;
}
```

The salt is added after the hashed value;
to independently verify the hashing mechanism:

```console
$ echo -n "" | md5sum
```





### sticky_strict

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `sticky_strict` `on` | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------|
| Default                                                                                  | `sticky_strict off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                        |

When enabled, Angie will return a connection error to the client
if the desired server is unavailable,
instead of falling back to another available server,
which is the default behavior when no matching server is found.





### upstream

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `upstream` name { ... }   |
|------------------------------------------------------------------------------------------|---------------------------|
| Default                                                                                  | —                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream                    |

Describes a group of servers. Servers can listen on different ports. In addition, servers listening on TCP and UNIX domain sockets can be mixed.

Example:

```nginx
upstream backend {
    zone backend 1m;
    server backend1.example.com:1935 weight=5;
    server 127.0.0.1:1935            max_fails=3 fail_timeout=30s;
    server unix:/tmp/backend2;
    server backend3.example.com:1935 resolve;

    server backup1.example.com:1935  backup;
}
```



By default, connections are distributed between the servers using a weighted round-robin balancing method. In the above example, each 7 connections will be distributed as follows: 5 connections go to backend1.example.com:1935 and one connection to each of the second and third servers. The distribution is *smooth*: a higher-weight server's connections are spread across the rotation rather than sent in a single burst.

If an error occurs during communication with a server, the connection will be passed to the next server, and so on until all of the functioning servers will be tried. If communication with all servers fails, the connection will be closed.

#### NOTE
By default, a server that fails an occasional attempt
without reaching [max_fails](#s-max-fails)
temporarily receives a smaller share of connections,
regaining its full share over the connections that follow.
This differs from [slow_start](#s-slow-start),
which ramps a server back up only after it has been
marked unavailable and has recovered.





### zone

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `zone` name [size];   |
|------------------------------------------------------------------------------------------|-----------------------|
| Default                                                                                  | —                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream              |

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), support for this
directive can be disabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--without-stream_upstream_zone_module`.

Defines the name and size of the shared memory zone that stores the group's configuration and runtime state, shared between worker processes. Multiple groups can use the same zone. In this case, it is sufficient to specify the size only once.

#### NOTE
The zone's content is only preserved on reload when the configured
`size` is unchanged. Any size change — increase or decrease —
causes the zone to be re-created empty.

#### NOTE
Upstream metrics are collected only when this zone is configured. Without it,
the group does not appear in [/status/stream/upstreams/](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-stream-upstreams), the
[TCP/UDP Upstreams Widget](https://en.angie.software//angie/docs/configuration/monitoring.md#tcp-udp-upstreams-widget), or [Prometheus](https://en.angie.software//angie/docs/configuration/modules/http/http_prometheus.md#http-prometheus) output, and no
warning is logged.



## Built-in Variables

The `stream_upstream` module supports the following built-in variables:



### `$sticky_sessid`

Used with `remote_action` in [sticky](#s-u-sticky);
stores the initial session identifier taken from `lookup`.



### `$sticky_sid`

Used with `remote_action` in [sticky](#s-u-sticky);
stores the server identifier previously associated with the session.

`sticky_sid` contains the value of the `sid=` parameter
from the `server` directive in the [upstream](#s-u-upstream) block, if specified,
or the MD5 hash of the server name.



### `$upstream_addr`

stores the IP address and port, or the path to the UNIX domain socket of the upstream server. If several servers were contacted during proxying, their addresses are separated by commas, e.g.:

> 192.168.1.1:1935, 192.168.1.2:1935, unix:/tmp/sock

If a server cannot be selected, the variable keeps the name of the [server group](#s-u-upstream).



### `$upstream_bytes_received`

number of bytes received from an upstream server. Values from several connections are separated by commas and colons like addresses in the [$upstream_addr](#v-s-upstream-addr) variable.



### `$upstream_bytes_sent`

number of bytes sent to an upstream server. Values from several connections are separated by commas and colons like addresses in the [$upstream_addr](#v-s-upstream-addr) variable.



### `$upstream_connect_time`

time to connect to the upstream server; the time is kept in seconds with millisecond resolution. Times of several connections are separated by commas and colons like addresses in the [$upstream_addr](#v-s-upstream-addr) variable.



### `$upstream_current_addr` (PRO)

address of the proxied server selected for the current connection attempt;
unlike [$upstream_addr](#v-s-upstream-addr), which accumulates the addresses of every server
tried across retries, this variable always holds a single address and is
available immediately after the server is selected, including while
[proxy_bind](https://en.angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-bind) variables are evaluated.



### `$upstream_first_byte_time`

time to receive the first byte of data; the time is kept in seconds with millisecond resolution. Times of several connections are separated by commas like addresses in the [$upstream_addr](#v-s-upstream-addr) variable.



### `$upstream_session_time`

session duration in seconds with millisecond resolution. Times of several connections are separated by commas like addresses in the [$upstream_addr](#v-s-upstream-addr) variable.



### `$upstream_sticky_status`

Status of sticky connections.

| `""`   | Connection routed to a server group where sticky is not enabled.                                    |
|--------|-----------------------------------------------------------------------------------------------------|
| `NEW`  | Connection does not contain sticky information.                                                     |
| `HIT`  | Connection with sticky information routed to the desired server.                                    |
| `MISS` | Connection with sticky information routed to a server
selected by the load balancing algorithm. |

Values from multiple connections are separated by commas and colons,
similar to addresses in the [$upstream_addr](#v-s-upstream-addr) variable.


# https://en.angie.software/angie/docs/configuration/modules/stream/stream_upstream_probe.md





# Upstream Probe

The module implements active health probes
for [Upstream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#stream-upstream).



## Configuration Example

```nginx
server {
    listen ...;

    # ...
    proxy_pass backend;
    upstream_probe_timeout 1s;

    upstream_probe backend_probe
        port=12345
        interval=5s
        test=$good
        essential
        fails=3
        passes=3
        max_response=512k
        mode=onfail
        "send=data:GET / HTTP/1.0\r\n\r\n";
}
```

#### NOTE
According to RFC 2616 (HTTP/1.1) and RFC 9110 (HTTP Semantics), HTTP headers
must be separated by a CRLF sequence (`\r\n`) rather than just
`\n`.



## Directives





### upstream_probe (PRO)

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `upstream_probe` name [`port=`number] [`interval=`time] [`test=`condition] [`essential` [`persistent`]] [`fails=`number] [`passes=`number] [`max_response=`size] [`mode=``always` | `idle` | `onfail`] [`udp`] [`send=`string];   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | —                                                                                                                                                                                                                                 |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | server                                                                                                                                                                                                                            |

Defines an active health probe for servers within the [upstream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-upstream) group
specified in the [proxy_pass](https://en.angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-pass) directive
in the same `server` context where the `upstream_probe` directive is located.

A server passes the probe if the request to it succeeds, considering all
parameter settings of the `upstream_probe` directive and all parameters that
affect how upstreams are used by the `server` context where it is defined,
including the [proxy_next_upstream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-next-upstream) directive.

To make use of the probes,
the upstream must have a shared memory zone ([zone](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-zone)).
One upstream may be configured with several probes.

The following parameters are accepted:

| `name`         | Mandatory name of the probe.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
|----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `port`         | Alternative port number for the probe request.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `interval`     | [Interval](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units) between probes.
By default — `5s`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `test`         | The condition for the probe, defined as a string of variables.
If the variables' substitution yields `""` or `"0"`,
the probe is not passed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `essential`    | If set, the initial state of the server is being checked, so the server
doesn't receive client requests until the probe is passed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `persistent`   | Setting this parameter requires enabling `essential` first;
`persistent` servers that were deemed healthy prior to a
[configuration reload](https://en.angie.software//angie/docs/configuration/configfile.md#configfile-reloading)
start receiving requests without being required to pass this probe first.                                                                                                                                                                                                                                                                                                                                          |
| `fails`        | Number of subsequent failed probes that
renders the server unhealthy.
By default — 1.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `passes`       | Number of subsequent passed probes that
renders the server healthy.
By default — 1.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `max_response` | Maximum memory size for the response. If a zero
[value](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units) is specified, response waiting is disabled.
By default — `256k`.                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `mode`         | Probe mode, depending on the servers' health:

- `always` — servers are probed regardless of their state;
- `idle` — probes affect unhealthy servers and servers where
  `interval` has elapsed since the last client request.
- `onfail` — only unhealthy servers are probed.

By default — `always`.                                                                                                                                                                                                                                                                                                                                 |
| `udp`          | If specified, the UDP protocol is used for probing.
By default, TCP is used for probing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `send`         | Data sent for the probe: inline data with the `data:` prefix
or a file path (absolute or relative to `/usr/local/angie/`).

When using a file:

- The [worker process](https://en.angie.software//angie/docs/configuration/modules/core.md#worker-processes) opens and reads
  the file on each access; the content is not cached in memory.
- Configuration reload is not required when the file changes;
  the new content will be read on the next access.
- Required access permissions: `644` for the file,
  `755` for the directory.
- Update files using the move command (`mv`),
  not by direct editing. |

Example:

```nginx
upstream backend {
    zone backend 1m;

    server a.example.com;
    server b.example.com;
}

map $upstream_probe_response $good {
    ~200    "1";
    default  "";
}

server {
    listen ...;

    # ...
    proxy_pass backend;
    upstream_probe_timeout 1s;

    upstream_probe backend_probe
        port=12345
        interval=5s
        test=$good
        essential
        persistent
        fails=3
        passes=3
        max_response=512k
        mode=onfail
        "send=data:GET / HTTP/1.0\r\n\r\n";
}
```

Details of probe operation:

- Initially, the server won't receive client requests
  until it passes *all* `essential` probes configured for it,
  skipping `persistent` ones if the configuration was reloaded
  and the server was deemed healthy prior to that.
  If there are no such probes, the server is considered healthy.
- The server is considered unhealthy and won't receive client requests,
  if *any* of the probes configured for it hits `fails`
  or the server reaches [max_fails](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-max-fails).
- For an unhealthy server to be considered healthy again,
  *all* probes configured for it must reach their respective `passes`;
  after that, [max_fails](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-max-fails) is also considered.





### upstream_probe_timeout (PRO)

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `upstream_probe_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `upstream_probe_timeout 50s;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | server                                                                                                                  |

Sets the maximum idle [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units) for a connection established with the server for health probes configured using the [upstream_probe (PRO)](#s-u-upstream-probe) directive; if this limit is exceeded, the connection will be closed.



## Built-in Variables

The `stream_upstream` module supports the following built-in variables:



### `$upstream_probe` (PRO)

Name of the currently active [upstream_probe](#s-u-upstream-probe).



### `$upstream_probe_response` (PRO)

Contents of the response received during an active probe configured by
[upstream_probe](#s-u-upstream-probe).


# https://en.angie.software/angie/docs/configuration/modules/mail.md






# Mail Module

The core mail module implements basic functionality for a mail proxy server:
this includes support for SMTP, IMAP, and POP3 protocols, configuring server
blocks, mail request routing, user authentication, and SSL/TLS support for
securing mail connections.

The other modules in this section extend this functionality, allowing you to
flexibly configure and optimize the mail server for various scenarios and
requirements.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module isn't built
by default; it must be enabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--with-mail`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Configuration Example

```nginx
worker_processes auto;

error_log /var/log/angie/error.log info;

events {
    worker_connections  1024;
}

mail {
    server_name       mail.example.com;
    auth_http         localhost:9000/cgi-bin/auth.cgi;

    imap_capabilities IMAP4rev1 UIDPLUS IDLE LITERAL+ QUOTA;

    pop3_auth         plain apop cram-md5;
    pop3_capabilities LAST TOP USER PIPELINING UIDL;

    smtp_auth         login plain cram-md5;
    smtp_capabilities "SIZE 10485760" ENHANCEDSTATUSCODES 8BITMIME DSN;
    xclient           off;

    server {
        listen   25;
        protocol smtp;
    }
    server {
        listen   110;
        protocol pop3;
        proxy_pass_error_message on;
    }
    server {
        listen   143;
        protocol imap;
    }
    server {
        listen   587;
        protocol smtp;
    }
}
```



## Directives





### error_log_user_tag

#### Versionadded
Added in version 1.12.0.

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `error_log_user_tag` value;   |
|------------------------------------------------------------------------------------------|-------------------------------|
| Default                                                                                  | —                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                  |

Adds a session-specific tag to [error_log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log) records. Unlike its
[http](https://en.angie.software//angie/docs/configuration/modules/http/index.md#error-log-user-tag) and [stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#s-error-log-user-tag)
counterparts, the value is a static string and cannot contain variables.
The directive can be specified multiple times to add multiple tags.
Tags can be matched with `filter=tag:` in [error_log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log).





### listen

#### Versionchanged
Changed in version 1.10.0.

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `listen` address[:port] [`ssl`] [`proxy_protocol`] [`backlog=`number] [`rcvbuf=`size] [`sndbuf=`size] [`bind`] [`ipv6only=``on` | `off`] [`reuseport`] [`so_keepalive=`on|off|[`keepidle`]:[`keepintvl`]:[`keepcnt`]];   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | —                                                                                                                                                                                                                        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | server                                                                                                                                                                                                                   |

Sets the address and port for the socket on which the server will accept connections. It is possible to specify just the port, and Angie will listen on all available IPv4 interfaces (and IPv6, if enabled). The address can also be a hostname, for example:

```nginx
listen 127.0.0.1:110;
listen *:110;
listen 110;     # same as *:110
listen localhost:110;
```

IPv6 addresses are specified in square brackets:

```nginx
listen [::1]:110;
listen [::]:110;
```

UNIX-domain sockets are specified with the `unix:` prefix:

```nginx
listen unix:/var/run/angie.sock;
```

#### NOTE
Different servers must listen on different address:port pairs.

| `ssl`            | specifies that all connections accepted on this port should work in SSL mode.                                                                                                                                                                                                                                                                                                                                 |
|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `proxy_protocol` | specifies that all connections accepted on this port should use
the PROXY protocol. Obtained information is passed to the
[authentication server](https://en.angie.software//angie/docs/configuration/modules/mail/mail_auth_http.md#mail-auth-http) and can be used to
[change the client address](https://en.angie.software//angie/docs/configuration/modules/mail/mail_realip.md#mail-realip). |

The `listen` directive can have several additional parameters specific to socket-related system calls.

| `backlog=`number      | sets the backlog parameter in the `listen()` call that limits the
maximum length for the queue of pending connections. By default,
backlog is set to -1 on FreeBSD, DragonFly BSD, and macOS, and
to 511 on other platforms.                                                                                                                                                                                                                                                                                                                                                                                                                                  |
|-----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `rcvbuf=`size         | sets the receive buffer size (the SO_RCVBUF option) for the listening socket.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `sndbuf=`size         | sets the send buffer size (the SO_SNDBUF option) for the listening socket.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `bind`                | instructs to make a separate `bind()` call for a
given address:port pair. The fact is that if there are several
`listen` directives with the same port but different addresses,
and one of the `listen` directives listens on all addresses for the
given port (\*:port), Angie will `bind()` only to \*:port.
It should be noted that the `getsockname()` system call will be
made in this case to determine the address that accepted the connection.
If the backlog, rcvbuf, sndbuf, ipv6only,
reuseport, or so_keepalive parameters are used then for a
given address:port pair a separate `bind()` call will always be
made. |
| `ipv6only=on` | `off` | determines (via the IPV6_V6ONLY socket option) whether an IPv6 socket listening on a wildcard address [::] will accept only IPv6 connections or both IPv6 and IPv4 connections. This parameter is turned on by default. It can only be set once on start.                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `multipath`           | enables accepting connections via [Multipath TCP](https://en.wikipedia.org/wiki/Multipath_TCP) (MPTCP),
supported in Linux kernel version 5.6 and later.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

`so_keepalive=on` | `off` | [`keepidle`]:[`keepintvl`]:[`keepcnt`]

Configures the "TCP keepalive" behavior for the listening socket.

| `''`   | if this parameter is omitted then the operating system's settings will be in effect for the socket   |
|--------|------------------------------------------------------------------------------------------------------|
| `on`   | the SO_KEEPALIVE option is turned on for the socket                                                  |
| `off`  | the SO_KEEPALIVE option is turned off for the socket                                                 |

Some operating systems support setting of TCP keepalive parameters on a
per-socket basis using the `TCP_KEEPIDLE`, `TCP_KEEPINTVL`, and
`TCP_KEEPCNT` socket options. On such systems, they can be configured using the `keepidle`,
`keepintvl`, and `keepcnt` parameters. One or two parameters may be omitted, in
which case the system default setting for the corresponding socket option will
be in effect.

For example,

```nginx
so_keepalive=30m::10
```

will set the idle timeout (`TCP_KEEPIDLE`) to 30 minutes, leave the probe interval (`TCP_KEEPINTVL`) at its system default, and set the probes count (`TCP_KEEPCNT`) to 10 probes.

Different servers must listen on different address:port pairs.





### mail

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `mail` { ... }   |
|------------------------------------------------------------------------------------------|------------------|
| Default                                                                                  | —                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | main             |

Provides the configuration file context in which the mail server directives are specified.





### max_commands

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `max_commands` number;   |
|------------------------------------------------------------------------------------------|--------------------------|
| Default                                                                                  | `max_commands 1000;`     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server             |

Sets the maximum number of commands issued during authentication
to enhance protection against DoS attacks.





### max_errors

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `max_errors` number;   |
|------------------------------------------------------------------------------------------|------------------------|
| Default                                                                                  | `max_errors 5;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server           |

Sets the number of protocol errors after which the connection is closed.





### protocol

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `protocol` imap | pop3 | smtp;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | —                                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | server                           |

Sets the protocol for a proxied server. Supported protocols are [IMAP](https://en.angie.software//angie/docs/configuration/modules/mail/mail_imap.md#mail-imap), [POP3](https://en.angie.software//angie/docs/configuration/modules/mail/mail_pop3.md#mail-pop3), and [SMTP](https://en.angie.software//angie/docs/configuration/modules/mail/mail_smtp.md#mail-smtp).

If the directive is not set, the protocol can be detected automatically based on the well-known port specified in the `listen` directive:

```console
imap: 143, 993
pop3: 110, 995
smtp: 25, 587, 465
```

When [building from source](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), unnecessary protocols can be disabled using the
`‑‑without‑mail_imap_module`, `‑‑without‑mail_pop3_module`, and
`‑‑without‑mail_smtp_module` [build options](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure).





### resolver

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `resolver` [address ...] [`conf` [`=`file]] [`valid=`time] [`ipv4=``on` | `off`] [`ipv6=``on` | `off`] [`status_zone=`zone] | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `resolver off;`                                                                                                                        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                                                                                                                           |

Configures name servers used to find the client's hostname to pass it to the [authentication server](https://en.angie.software//angie/docs/configuration/modules/mail/mail_auth_http.md#mail-auth-http), and in the [XCLIENT](https://en.angie.software//angie/docs/configuration/modules/mail/mail_proxy.md#m-xclient) command when proxying SMTP. For example:

```nginx
resolver 127.0.0.53 [::1]:5353;
```

The address can be specified as a domain name or IP address, with an optional port. If port is not specified, the port 53 is used. Name servers are queried in a round-robin fashion.

At least one DNS server address or the `conf` parameter must be specified,
except in the `resolver off;` form.

Besides explicit server addresses, the directive recognizes:

| `off`            | disables resolving of the client hostname and cancels an inherited
directive value                     |
|------------------|------------------------------------------------------------------------------------------------------------|
| `conf` [`=`file] | reads DNS server addresses from the specified file, or from
`/etc/resolv.conf` if no file is specified |

The file may contain `nameserver` lines in the same format used by the
system resolver:

```text
nameserver 127.0.1.4
nameserver 127.0.1.5
```

Addresses read from the file are added to any addresses specified explicitly
in the directive, and all of them are then queried together in a
round-robin fashion. If the file is absent, cannot be read, or lists no
addresses, and none are configured explicitly, Angie falls back to the
default server `127.0.0.1:53`.

At runtime, Angie re-reads the file when it changes, updating the set of DNS
servers.

#### NOTE
Prefer a local trusted resolver such as `127.0.0.53` (systemd-resolved)
over a public one (e.g. `8.8.8.8`). Public resolvers expose DNS queries
to third parties and increase susceptibility to cache-poisoning attacks.

#### NOTE
The directive value is inherited by nested blocks
and can be overridden in them if necessary.
Within a single block the directive may be specified only once;
repeating it is a configuration error.

When looking up the client's hostname, Angie caches each DNS answer for the
duration of its TTL. The optional `valid` parameter overrides this
period:

| `valid`   | *optional* parameter allows overriding cached entry validity   |
|-----------|----------------------------------------------------------------|
```nginx
resolver 127.0.0.53 [::1]:5353 valid=30s;
```

By default, Angie will look up both IPv4 and IPv6 addresses while resolving.

| `ipv4=off`    | disables looking up of IPv4 addresses                                                                                 |
|---------------|-----------------------------------------------------------------------------------------------------------------------|
| `ipv6=off`    | disables looking up of IPv6 addresses                                                                                 |
| `status_zone` | *optional* parameter, enables collection of information about DNS server requests and responses in the specified zone |





### resolver_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `resolver_timeout` time;   |
|------------------------------------------------------------------------------------------|----------------------------|
| Default                                                                                  | `resolver_timeout 30s;`    |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server               |

Sets a timeout for name resolution, for example:

```nginx
resolver_timeout 5s;
```





### server

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `server` { ... }   |
|------------------------------------------------------------------------------------------|--------------------|
| Default                                                                                  | —                  |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail               |

Sets the configuration for a server.





### server_name

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `server_name` name;     |
|------------------------------------------------------------------------------------------|-------------------------|
| Default                                                                                  | `server_name hostname`; |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server            |

Sets the server name that is used:

* in the initial POP3/SMTP server greeting;
* in the salt during the SASL CRAM-MD5 authentication;
* in the EHLO command when connecting to the SMTP backend, if the passing of the [XCLIENT](https://en.angie.software//angie/docs/configuration/modules/mail/mail_proxy.md#m-xclient) command is enabled.

If the directive is not specified, the machine's hostname is used.





### timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `timeout` time;   |
|------------------------------------------------------------------------------------------|-------------------|
| Default                                                                                  | `timeout 60s;`    |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server      |

Sets the timeout that is used before proxying to the backend starts.


# https://en.angie.software/angie/docs/configuration/modules/mail/mail_auth_http.md





# Auth HTTP

The module enables subrequest-based authentication by sending an additional HTTP
request before processing the main request. If the subrequest returns a 2xx
status, the main request proceeds; if it returns 401 or 403, the appropriate
error is sent to the user, while any other response triggers a 500 error. This
approach is typically used to delegate authentication to external services,
unify authentication across applications, or integrate with third-party systems
like OAuth or LDAP.



## Directives





### auth_http

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `auth_http` uri;   |
|------------------------------------------------------------------------------------------|--------------------|
| Default                                                                                  | —                  |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server       |

Sets the URL of the HTTP authentication server. The protocol is described [below](#v-m-protocol).





### auth_http_header

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `auth_http_header` header value;   |
|------------------------------------------------------------------------------------------|------------------------------------|
| Default                                                                                  | —                                  |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                       |

Appends the specified header to requests sent to the authentication server. This header can be used as a shared secret to verify that the request comes from Angie. For example:

```nginx
auth_http_header X-Auth-Key "secret_string";
```





### auth_http_pass_client_cert

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `auth_http_pass_client_cert` `on` | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------------------------|
| Default                                                                                  | `auth_http_pass_client_cert off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                                 |

Appends the `Auth-SSL-Cert` header with the [client certificate](https://en.angie.software//angie/docs/configuration/modules/mail/mail_ssl.md#m-ssl-verify-client) in PEM format (urlencoded) to requests sent to the authentication server.





### auth_http_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `auth_http_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `auth_http_timeout 60s;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                                                                                                       |

Sets the timeout for communication with the authentication server.



## Protocol

The HTTP protocol is used to communicate with the authentication server. The data in the response body is ignored; information is passed only in the headers.



### Examples of requests and responses:

Request:

```console
GET /auth HTTP/1.0
Host: localhost
Auth-Method: plain # plain/apop/cram-md5/external/xoauth2/oauthbearer/none
Auth-User: user
Auth-Pass: password
Auth-Protocol: imap # imap/pop3/smtp
Auth-Login-Attempt: 1
Client-IP: 192.0.2.42
Client-Host: client.example.org
```

Good response:

```console
HTTP/1.0 200 OK
Auth-Status: OK
Auth-Server: 198.51.100.1
Auth-Port: 143
```

Bad response:

```console
HTTP/1.0 200 OK
Auth-Status: Invalid login or password
Auth-Wait: 3
```

If there is no `Auth-Wait` header, an error will be returned and the connection will be closed. The current implementation allocates memory for each authentication attempt. The memory is freed only at the end of a session. Therefore, the number of invalid authentication attempts in a single session must be limited — the server must respond without the `Auth-Wait` header after 10-20 attempts (the attempt number is passed in the `Auth-Login-Attempt` header).

When APOP or CRAM-MD5 is used, the request-response will look as follows:

```console
GET /auth HTTP/1.0
Host: localhost
Auth-Method: apop
Auth-User: user
Auth-Salt: <238188073.1163692009@mail.example.com>
Auth-Pass: auth_response
Auth-Protocol: imap
Auth-Login-Attempt: 1
Client-IP: 192.0.2.42
Client-Host: client.example.org
```

Good response:

```console
HTTP/1.0 200 OK
Auth-Status: OK
Auth-Server: 198.51.100.1
Auth-Port: 143
Auth-Pass: plain-text-pass
```

When XOAUTH2 or OAUTHBEARER is used, the `Auth-User` and `Auth-Pass`
headers contain the user identity and bearer token extracted from the initial
SASL response.

If the `Auth-User` header exists in the response, it overrides the username used to authenticate with the backend.

For SMTP, the response additionally takes into account the `Auth-Error-Code` header — if it exists, it is used as a response code in case of an error. Otherwise, the 535 5.7.0 code will be added to the `Auth-Status` header by default.

For XOAUTH2 and OAUTHBEARER, an error response may also include the
`Auth-Error-SASL` header. Its value is sent to the client as an additional
SASL challenge (SMTP: 334, IMAP/POP3: +). After the client responds with an
empty response for XOAUTH2 or `AQ==` for OAUTHBEARER, the error from
`Auth-Status` is returned.

For example, if the following response is received from the authentication server:

```console
HTTP/1.0 200 OK
Auth-Status: Temporary server problem, try again later
Auth-Error-Code: 451 4.3.0
Auth-Wait: 3
```

then the SMTP client will receive an error

```console
451 4.3.0 Temporary server problem, try again later
```

If proxying SMTP does not require authentication, the request will look as follows:

```console
GET /auth HTTP/1.0
Host: localhost
Auth-Method: none
Auth-User:
Auth-Pass:
Auth-Protocol: smtp
Auth-Login-Attempt: 1
Client-IP: 192.0.2.42
Client-Host: client.example.org
Auth-SMTP-Helo: client.example.org
Auth-SMTP-From: MAIL FROM: <>
Auth-SMTP-To: RCPT TO: 
```

For SSL/TLS client connections, the `Auth-SSL` header is added, and `Auth-SSL-Verify` will contain the result of client certificate verification, if [enabled](https://en.angie.software//angie/docs/configuration/modules/mail/mail_ssl.md#m-ssl-verify-client): `SUCCESS`, `FAILED:reason`, and `NONE` if a certificate was not present.

When the client certificate was present, its details are passed in the following request headers: `Auth-SSL-Subject`, `Auth-SSL-Issuer`, `Auth-SSL-Serial`, and `Auth-SSL-Fingerprint`. If [auth_http_pass_client_cert](#m-auth-http-pass-client-cert) is enabled, the certificate itself is passed in the `Auth-SSL-Cert` header. The protocol and cipher of the established connection are passed in the `Auth-SSL-Protocol` and `Auth-SSL-Cipher` headers. The request will look as follows:

```console
GET /auth HTTP/1.0
Host: localhost
Auth-Method: plain
Auth-User: user
Auth-Pass: password
Auth-Protocol: imap
Auth-Login-Attempt: 1
Client-IP: 192.0.2.42
Auth-SSL: on
Auth-SSL-Protocol: TLSv1.3
Auth-SSL-Cipher: TLS_AES_256_GCM_SHA384
Auth-SSL-Verify: SUCCESS
Auth-SSL-Subject: /CN=example.com
Auth-SSL-Issuer: /CN=example.com
Auth-SSL-Serial: C07AD56B846B5BFF
Auth-SSL-Fingerprint: 29d6a80a123d13355ed16b4b04605e29cb55a5ad
```

When the [PROXY protocol](https://en.angie.software//angie/docs/configuration/modules/mail/index.md#m-listen-ssl-proxy) is used, its details are passed in the following request headers: `Proxy-Protocol-Addr`, `Proxy-Protocol-Port`, `Proxy-Protocol-Server-Addr`, and `Proxy-Protocol-Server-Port`.


# https://en.angie.software/angie/docs/configuration/modules/mail/mail_imap.md





# IMAP

The module enables IMAP mail protocol support, allowing the server to interact
with mail storage systems. It establishes connections to IMAP servers, processes
common commands such as listing mailboxes and retrieving messages, and provides
secure authentication and message status management.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by
default together with the [Mail](https://en.angie.software//angie/docs/configuration/modules/mail/index.md#mail-core) module (enabled with
`--with-mail`); it can be disabled with the
[build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure) `--without-mail_imap_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Directives





### imap_auth

#### Versionchanged
Changed in version 1.11.0.

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `imap_auth` method ...;   |
|------------------------------------------------------------------------------------------|---------------------------|
| Default                                                                                  | `imap_auth plain;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server              |

Sets permitted methods of authentication for IMAP clients. Supported methods are:

| `plain`       | [LOGIN](https://datatracker.ietf.org/doc/html/rfc3501), [AUTH=PLAIN](https://datatracker.ietf.org/doc/html/rfc4616)                        |
|---------------|--------------------------------------------------------------------------------------------------------------------------------------------|
| `login`       | [AUTH=LOGIN](https://datatracker.ietf.org/doc/html/draft-murchison-sasl-login-00)                                                          |
| `cram-md5`    | [AUTH=CRAM-MD5](https://datatracker.ietf.org/doc/html/rfc2195). In order for this method to work, the password must be stored unencrypted. |
| `external`    | [AUTH=EXTERNAL](https://datatracker.ietf.org/doc/html/rfc4422)                                                                             |
| `xoauth2`     | [AUTH=XOAUTH2](https://developers.google.com/gmail/imap/xoauth2-protocol)                                                                  |
| `oauthbearer` | [AUTH=OAUTHBEARER](https://datatracker.ietf.org/doc/html/rfc7628)                                                                          |

Plain text authentication methods (the `LOGIN` command,
`AUTH=PLAIN`, and `AUTH=LOGIN`) are always enabled, though if the
`plain` and `login` methods are not specified, `AUTH=PLAIN` and
`AUTH=LOGIN` will not be automatically included in
[imap_capabilities](#m-imap-capabilities).





### imap_capabilities

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `imap_capabilities` extension ...;           |
|------------------------------------------------------------------------------------------|----------------------------------------------|
| Default                                                                                  | `imap_capabilities IMAP4 IMAP4rev1 UIDPLUS;` |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                                 |

Sets the [IMAP protocol](https://datatracker.ietf.org/doc/html/rfc3501) extensions list that is passed to the client in response to the CAPABILITY command. The authentication methods specified in the [imap_auth](#m-imap-auth) directive and [STARTTLS](https://datatracker.ietf.org/doc/html/rfc2595) are automatically added to this list depending on the [starttls](https://en.angie.software//angie/docs/configuration/modules/mail/mail_ssl.md#m-starttls) directive value.

It makes sense to specify the extensions supported by the IMAP backends to which the clients are proxied (if these extensions are related to commands used after the authentication, when Angie transparently proxies a client connection to the backend).







### imap_client_buffer

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `imap_client_buffer` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `imap_client_buffer 4k|8k;`                                                                                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                                                                                                        |

Sets the size of the buffer used for reading IMAP commands. By default, the buffer size is equal to one memory page. This is either 4K or 8K, depending on a platform.


# https://en.angie.software/angie/docs/configuration/modules/mail/mail_pop3.md





# POP3

The module enables POP3 mail protocol support, allowing the server to download
messages from mail servers. It connects to POP3 servers, retrieves message
headers and content, provides secure authentication, and manages message
statuses such as downloaded or deleted.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by
default together with the [Mail](https://en.angie.software//angie/docs/configuration/modules/mail/index.md#mail-core) module (enabled with
`--with-mail`); it can be disabled with the
[build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure) `--without-mail_pop3_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Directives





### pop3_auth

#### Versionchanged
Changed in version 1.11.0.

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `pop3_auth` method ...;   |
|------------------------------------------------------------------------------------------|---------------------------|
| Default                                                                                  | `pop3_auth plain;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server              |

Sets permitted methods of authentication for POP3 clients. Supported methods are:

| `plain`       | [USER/PASS](https://datatracker.ietf.org/doc/html/rfc1939), [AUTH PLAIN](https://datatracker.ietf.org/doc/html/rfc4616), [AUTH LOGIN](https://datatracker.ietf.org/doc/html/draft-murchison-sasl-login-00)   |
|---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `apop`        | [APOP](https://datatracker.ietf.org/doc/html/rfc1939). In order for this method to work, the password must be stored unencrypted.                                                                            |
| `cram-md5`    | [AUTH=CRAM-MD5](https://datatracker.ietf.org/doc/html/rfc2195). In order for this method to work, the password must be stored unencrypted.                                                                   |
| `external`    | [AUTH=EXTERNAL](https://datatracker.ietf.org/doc/html/rfc4422)                                                                                                                                               |
| `xoauth2`     | [AUTH=XOAUTH2](https://developers.google.com/gmail/imap/xoauth2-protocol)                                                                                                                                    |
| `oauthbearer` | [AUTH=OAUTHBEARER](https://datatracker.ietf.org/doc/html/rfc7628)                                                                                                                                            |

Plain text authentication methods (`USER/PASS`, `AUTH PLAIN` and
`AUTH LOGIN`) are always enabled, though if the `plain` method is
not specified, `AUTH PLAIN` and `AUTH LOGIN` will not be
automatically included in [pop3_capabilities](#m-pop3-capabilities).





### pop3_capabilities

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `pop3_capabilities` extension ...;   |
|------------------------------------------------------------------------------------------|--------------------------------------|
| Default                                                                                  | `pop3_capabilities TOP USER UIDL;`   |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                         |

Sets the [POP3 protocol](https://datatracker.ietf.org/doc/html/rfc2449) extensions list that is passed to the client in response to the CAPA command. The authentication methods specified in the [pop3_auth](#m-pop3-auth) directive ([SASL](https://datatracker.ietf.org/doc/html/rfc2449) extension) and [STLS](https://datatracker.ietf.org/doc/html/rfc2595) are automatically added to this list depending on the [starttls](https://en.angie.software//angie/docs/configuration/modules/mail/mail_ssl.md#m-starttls) directive value.

It makes sense to specify the extensions supported by the POP3 backends to which the clients are proxied (if these extensions are related to commands used after the authentication, when Angie transparently proxies the client connection to the backend).


# https://en.angie.software/angie/docs/configuration/modules/mail/mail_proxy.md





# Proxy

The module enables support for mail protocols (POP3, IMAP, SMTP), allowing the
server to act as a proxy between clients and mail servers. It establishes
connections with servers, performs secure authentication using plain text,
SSL/TLS, or STARTTLS, properly routes client traffic, and supports flexible
authentication method and server selection.



## Directives





### proxy_buffer

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_buffer` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `proxy_buffer 4k|8k;`                                                                                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                                                                                                  |

Sets the size of the buffer used for proxying. By default, the buffer size is equal to one memory page. Depending on a platform, it is either 4K or 8K.





### proxy_pass_error_message

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_pass_error_message` `on` | `off`;   |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| Default                                                                                  | `proxy_pass_error_message off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                               |

Determines whether to pass the error message obtained during authentication on the backend to the client.

Usually, if authentication in Angie is successful, the backend cannot return an error. If it nevertheless returns an error, it means some internal error has occurred. In such cases the backend message may contain information that should not be shown to the client. However, responding with an error for the correct password is normal behavior for some POP3 servers. The directive should be enabled in this case.





### proxy_protocol

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_protocol` `on` | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | `proxy_protocol off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                     |

Enables the [PROXY protocol](http://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) for connections to a backend.





### proxy_smtp_auth

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_smtp_auth` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-----------------------------------|
| Default                                                                                  | `proxy_smtp_auth off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                      |

Enables or disables user authentication on the SMTP backend using the AUTH command.

If [XCLIENT](#m-xclient) is also enabled, then the XCLIENT command will not send the LOGIN parameter.





### proxy_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `proxy_timeout 24h;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                                                                                                   |

Sets the timeout between two successive read or write operations on client or proxied server connections. If no data is transmitted within this time, the connection is closed.





### xclient

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `xclient` `on` | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------|
| Default                                                                                  | `xclient on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server              |

Enables or disables the passing of the [XCLIENT](http://www.postfix.org/XCLIENT_README.html) command with client parameters when connecting to the SMTP backend.

With `XCLIENT`, the MTA is able to write client information to the log and
apply various limitations based on this data.

If `XCLIENT` is enabled then Angie passes the following commands when
connecting to the backend:

* `EHLO` with the [server name](https://en.angie.software//angie/docs/configuration/modules/mail/index.md#m-server-name)
* `XCLIENT`
* `EHLO` or `HELO`, as passed by the client

If the name [found](https://en.angie.software//angie/docs/configuration/modules/mail/index.md#m-resolver) by the client IP address points to the
same address, it is passed in the `NAME` parameter of the `XCLIENT`
command. If the name could not be found, points to a different address, or
[resolver](https://en.angie.software//angie/docs/configuration/modules/mail/index.md#m-resolver) is not specified, then `[UNAVAILABLE]` is
passed in the `NAME` parameter. If an error has occurred in the process of
resolving, the `[TEMPUNAVAIL]` value is used.

If `XCLIENT` is disabled, Angie passes the `EHLO` command with the
[server name](https://en.angie.software//angie/docs/configuration/modules/mail/index.md#m-server-name) when connecting to the backend if the client
has passed `EHLO`, or `HELO` with the server name, otherwise.


# https://en.angie.software/angie/docs/configuration/modules/mail/mail_realip.md





# RealIP

The module is used to change the client address and port to the ones sent in the
PROXY protocol header. The PROXY protocol must be previously enabled by setting
the `proxy_protocol` parameter in the [listen](https://en.angie.software//angie/docs/configuration/modules/mail/index.md#m-listen) directive.



## Configuration Example

```nginx
listen 110 proxy_protocol;

set_real_ip_from  192.168.1.0/24;
set_real_ip_from  192.168.2.1;
set_real_ip_from  2001:0db8::/32;
```



## Directives





### set_real_ip_from

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `set_real_ip_from` address | CIDR | `unix:`;   |
|------------------------------------------------------------------------------------------|------------------------------------------------|
| Default                                                                                  | —                                              |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                                   |

Defines trusted addresses that are known to send correct replacement addresses.
If the special value `unix:` is specified, all UNIX domain sockets will
be trusted.


# https://en.angie.software/angie/docs/configuration/modules/mail/mail_smtp.md





# SMTP

The module enables support for the SMTP mail protocol, allowing the server to
proxy outgoing email traffic between clients and mail servers. It
establishes connections to SMTP servers, supports secure authentication using
LOGIN or PLAIN methods, provides STARTTLS and SSL/TLS encryption, and routes
client requests based on authentication results.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module is built by
default together with the [Mail](https://en.angie.software//angie/docs/configuration/modules/mail/index.md#mail-core) module (enabled with
`--with-mail`); it can be disabled with the
[build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure) `--without-mail_smtp_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.



## Directives





### smtp_auth

#### Versionchanged
Changed in version 1.11.0.

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `smtp_auth` method ...;   |
|------------------------------------------------------------------------------------------|---------------------------|
| Default                                                                                  | `smtp_auth plain login;`  |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server              |

Sets permitted methods of [SASL authentication](https://datatracker.ietf.org/doc/html/rfc2554) for SMTP clients. Supported methods are:

| `plain`       | [AUTH PLAIN](https://datatracker.ietf.org/doc/html/rfc4616)                                                                                |
|---------------|--------------------------------------------------------------------------------------------------------------------------------------------|
| `login`       | [AUTH LOGIN](https://datatracker.ietf.org/doc/html/draft-murchison-sasl-login-00)                                                          |
| `cram-md5`    | [AUTH CRAM-MD5](https://datatracker.ietf.org/doc/html/rfc2195). In order for this method to work, the password must be stored unencrypted. |
| `external`    | [AUTH EXTERNAL](https://datatracker.ietf.org/doc/html/rfc4422)                                                                             |
| `xoauth2`     | [AUTH XOAUTH2](https://developers.google.com/gmail/imap/xoauth2-protocol)                                                                  |
| `oauthbearer` | [AUTH OAUTHBEARER](https://datatracker.ietf.org/doc/html/rfc7628)                                                                          |
| `none`        | Authentication is not required                                                                                                             |

Plain text authentication methods (`AUTH PLAIN` and `AUTH LOGIN`)
are always enabled, though if the `plain` and `login` methods are not specified,
`AUTH PLAIN` and `AUTH LOGIN` will not be automatically included in
[smtp_capabilities](#m-smtp-capabilities).





### smtp_capabilities

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `smtp_capabilities` extension ...;   |
|------------------------------------------------------------------------------------------|--------------------------------------|
| Default                                                                                  | —                                    |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                         |

Sets the SMTP protocol extensions list that is passed to the client in response to the EHLO command. The authentication methods specified in the [smtp_auth](#m-smtp-auth) directive and [STARTTLS](https://datatracker.ietf.org/doc/html/rfc3207) are automatically added to this list depending on the [starttls](https://en.angie.software//angie/docs/configuration/modules/mail/mail_ssl.md#m-starttls) directive value.

It makes sense to specify the extensions supported by the MTA to which the clients are proxied (if these extensions are related to commands used after authentication, when Angie transparently proxies the client connection to the backend).





### smtp_client_buffer

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `smtp_client_buffer` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `smtp_client_buffer 4k|8k;`                                                                                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                                                                                                        |

Sets the size of the buffer used for reading SMTP commands. By default, the buffer size is equal to one memory page. This is either 4K or 8K, depending on the platform.





### smtp_greeting_delay

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `smtp_greeting_delay` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `smtp_greeting_delay 0;`                                                                                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                                                                                                         |

Allows setting a delay before sending an SMTP greeting in order to reject clients who fail to wait for the greeting before sending SMTP commands.


# https://en.angie.software/angie/docs/configuration/modules/mail/mail_ssl.md





# SSL

The module enables SSL/TLS encryption support for mail proxy protocols (POP3,
IMAP, SMTP), allowing secure communication between clients and the server. It
provides SSL/TLS encryption for incoming connections, supports STARTTLS
upgrades, manages certificates and keys, and controls SSL settings such as
ciphers and protocol versions.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module isn't built
by default; it must be enabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--with-mail_ssl_module`.

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages), the
module is included in the build.

#### NOTE
This module requires the OpenSSL library.



## Configuration Example

To reduce the processor load it is recommended to

* set the number of [worker processes](https://en.angie.software//angie/docs/configuration/modules/core.md#worker-processes) equal to the number of processors,
* enable the [shared](#m-ssl-session-cache) session cache,
* disable the [built-in](#m-ssl-session-cache) session cache,
* and possibly increase the session [lifetime](#m-ssl-session-timeout) (by default, 5 minutes):

```nginx
worker_processes auto;

mail {

    ...

    server {
        listen              993 ssl;

        ssl_protocols       TLSv1.2 TLSv1.3;
        ssl_ciphers         AES128-SHA:AES256-SHA:RC4-SHA:DES-CBC3-SHA:RC4-MD5;
        ssl_certificate     /usr/local/angie/conf/cert.pem;
        ssl_certificate_key /usr/local/angie/conf/cert.key;
        ssl_session_cache   shared:SSL:10m;
        ssl_session_timeout 10m;

    #    ...
    }
```



## Directives





### ssl_certificate

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_certificate` file;   |
|------------------------------------------------------------------------------------------|---------------------------|
| Default                                                                                  | —                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server              |

Specifies a file with the certificate in the PEM format for the given server. If intermediate certificates should be specified in addition to a primary certificate, they should be specified in the same file in the following order: the primary certificate comes first, then the intermediate certificates. A secret key in the PEM format may be placed in the same file.

This directive can be specified multiple times to load certificates of different types, for example, RSA and ECDSA:

```nginx
server {
    listen              993 ssl;

    ssl_certificate     example.com.rsa.crt;
    ssl_certificate_key example.com.rsa.key;

    ssl_certificate     example.com.ecdsa.crt;
    ssl_certificate_key example.com.ecdsa.key;

#    ...
}
```

Only OpenSSL 1.0.2 or higher supports separate certificate chains for different certificates. With older versions, only one certificate chain can be used.

The value `data:`certificate`` can be specified instead of the `file`, which loads a certificate without using intermediate files.

Note that inappropriate use of this syntax may have its security implications, such as writing secret key data to [error log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log).





### ssl_certificate_compression

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_certificate_compression` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-----------------------------------------------|
| Default                                                                                  | `ssl_certificate_compression off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                                  |

Enables TLS 1.3 [compression](https://datatracker.ietf.org/doc/html/rfc8879) of server certificates.

#### NOTE
The directive is supported when using OpenSSL 3.2 or higher; the list of supported compression algorithms is provided by the library.

#### NOTE
The directive is supported when using [BoringSSL](https://boringssl.googlesource.com/boringssl/); the list of supported compression algorithms includes `zlib`.





### ssl_certificate_key

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_certificate_key` file;   |
|------------------------------------------------------------------------------------------|-------------------------------|
| Default                                                                                  | —                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                  |

Specifies a file with the secret key in the PEM format for the given server.

The value `engine:`name`:id` can be specified instead of the `file`, which loads a secret key with a specified id from the OpenSSL engine name.

The value `store:scheme:id` can be specified instead of the `file`, which is used to load a secret key with a specified id and OpenSSL provider registered URI scheme, such as [pkcs11](https://datatracker.ietf.org/doc/html/rfc7512).

The value `data:`key`` can be specified instead of the `file`, which loads a secret key without using intermediate files. Note that inappropriate use of this syntax may have its security implications, such as writing secret key data to [error log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log).





### ssl_ciphers

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ciphers` ciphers;          |
|------------------------------------------------------------------------------------------|---------------------------------|
| Default                                                                                  | `ssl_ciphers HIGH:!aNULL:!MD5;` |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                    |

Specifies the enabled ciphers. The ciphers are specified in the format understood by the OpenSSL library, for example:

```nginx
ssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;
```

The list of ciphers depends on the version of OpenSSL installed.
The full list can be viewed using the `openssl ciphers` command.

#### WARNING
The `ssl_ciphers` directive does *not* configure ciphers for TLS
1.3 when using OpenSSL. To tune TLS 1.3 ciphers with OpenSSL, use the
[ssl_conf_command](#m-ssl-conf-command) directive, which was added to support advanced
SSL configuration.

- In LibreSSL, TLS 1.3 ciphers *can* be configured using
  `ssl_ciphers`.
- In BoringSSL, TLS 1.3 ciphers cannot be configured at all.





### ssl_client_certificate

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_client_certificate` file;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | —                                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                     |

Specifies a file with trusted CA certificates in the PEM format used to [verify](#m-ssl-verify-client) client certificates.

The list of certificates will be sent to clients. If this is not desired, the [ssl_trusted_certificate](#m-ssl-trusted-certificate) directive can be used.





### ssl_conf_command

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_conf_command` name value;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | —                                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                     |

Sets arbitrary OpenSSL configuration [commands](https://docs.openssl.org/master/man3/SSL_CONF_cmd/).

#### NOTE
The directive is supported when using OpenSSL 1.0.2 or higher.
To configure TLS 1.3 ciphers with OpenSSL, use the `ciphersuites` command.

Several ssl_conf_command directives can be specified on the same level:

```nginx
ssl_conf_command Options PrioritizeChaCha;
ssl_conf_command Ciphersuites TLS_CHACHA20_POLY1305_SHA256;
```

These directives are inherited from the previous configuration level if and only if there are no ssl_conf_command directives defined on the current level.

#### WARNING
Note that configuring OpenSSL directly might result in unexpected behavior.





### ssl_crl

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_crl` file;   |
|------------------------------------------------------------------------------------------|-------------------|
| Default                                                                                  | —                 |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server      |

Specifies a file with revoked certificates (CRL) in the PEM format used to [verify](#m-ssl-verify-client) client certificates.





### ssl_dhparam

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_dhparam` file;   |
|------------------------------------------------------------------------------------------|-----------------------|
| Default                                                                                  | —                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server          |

Specifies a file with DH parameters for DHE ciphers.

#### WARNING
By default no parameters are set, and therefore DHE ciphers will not be used.





### ssl_ecdh_curve

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ecdh_curve` curve;   |
|------------------------------------------------------------------------------------------|---------------------------|
| Default                                                                                  | `ssl_ecdh_curve auto;`    |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server              |

Specifies a curve for ECDHE ciphers.

#### NOTE
When using OpenSSL 1.0.2 or higher, it is possible to specify multiple curves, for example:

```nginx
ssl_ecdh_curve prime256v1:secp384r1;
```

The special value `auto` instructs Angie to use a list built into the OpenSSL library when using OpenSSL 1.0.2 or higher, or prime256v1 with older versions.

#### NOTE
When using OpenSSL 1.0.2 or higher, this directive sets the list of curves supported by the server. Thus, in order for ECDSA certificates to work, it is important to include the curves used in the certificates.





### ssl_password_file

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_password_file` file;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| Default                                                                                  | —                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                |

Specifies a file with passphrases for [secret keys](#m-ssl-certificate-key) where each passphrase is specified on a separate line. Passphrases are tried in turn when loading the key.

Example:

```nginx
mail {
    ssl_password_file /etc/keys/global.pass;
    ...

    server {
        server_name mail1.example.com;
        ssl_certificate_key /etc/keys/first.key;
    }

    server {
        server_name mail2.example.com;

        # named pipe can also be used instead of a file
        ssl_password_file /etc/keys/fifo;
        ssl_certificate_key /etc/keys/second.key;
    }
}
```





### ssl_prefer_server_ciphers

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_prefer_server_ciphers` `on` | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| Default                                                                                  | `ssl_prefer_server_ciphers off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                                |

Specifies that server ciphers should be preferred over client ciphers when the SSLv3 and TLS protocols are used.





### ssl_protocols

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_protocols` [`SSLv2`] [`SSLv3`] [`TLSv1`] [`TLSv1.1`] [`TLSv1.2`] [`TLSv1.3`];   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
| Default                                                                                  | `ssl_protocols TLSv1.2 TLSv1.3;`                                                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                                                                         |

Enables the specified protocols.

#### NOTE
The TLSv1.1 and TLSv1.2 parameters work only when OpenSSL 1.0.1 or higher is used.

The TLSv1.3 parameter works only when OpenSSL 1.1.1 or higher is used.





### ssl_session_cache

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_session_cache` `off` | `none` | [builtin[:size]] [shared:name:size];   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| Default                                                                                  | `ssl_session_cache none;`                                                   |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                                                                |

Sets the types and sizes of caches that store session parameters. A cache can be of any of the following types:

| `off`     | the use of a session cache is strictly prohibited: Angie explicitly tells a client that sessions may not be reused.                                                                                                                                                                                                                                                                                                                                |
|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `none`    | the use of a session cache is gently disallowed: Angie tells a client that sessions may be reused, but does not actually store session parameters in the cache.                                                                                                                                                                                                                                                                                    |
| `builtin` | a cache built in OpenSSL; used by one worker process only. The cache size is specified in sessions. If size is not given, it is equal to 20480 sessions. Use of the built-in cache can cause memory fragmentation.                                                                                                                                                                                                                                 |
| `shared`  | a cache shared between all worker processes. The cache size is specified in bytes; one megabyte can store about 4000 sessions. Each shared cache should have an arbitrary name. A cache with the same name can be used in several servers. It is also used to automatically generate, store, and periodically rotate TLS session ticket keys unless configured explicitly using the [ssl_session_ticket_key](#m-ssl-session-ticket-key) directive. |

Both cache types can be used simultaneously, for example:

```nginx
ssl_session_cache builtin:1000 shared:SSL:10m;
```

but using only shared cache without the built-in cache should be more efficient.





### ssl_session_ticket_key

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_session_ticket_key` file;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | —                                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                     |

Sets a file with the secret key used to encrypt and decrypt TLS session tickets. The directive is necessary if the same key has to be shared between multiple servers. By default, a randomly generated key is used.

If several keys are specified, only the first key is used to encrypt TLS session tickets. This allows configuring key rotation, for example:

```nginx
ssl_session_ticket_key current.key;
ssl_session_ticket_key previous.key;
```

The file must contain 80 or 48 bytes of random data and can be created using the following command:

```console
$ openssl rand 80 > ticket.key
```

Depending on the file size either AES256 (for 80-byte keys) or AES128 (for 48-byte keys) is used for encryption.





### ssl_session_tickets

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_session_tickets` `on` | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------------|
| Default                                                                                  | `ssl_session_tickets on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                          |

Enables or disables session resumption through [TLS session tickets](https://datatracker.ietf.org/doc/html/rfc5077).





### ssl_session_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_session_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `ssl_session_timeout 5m;`                                                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                                                                                                         |

Specifies a time during which a client may reuse the session parameters.





### ssl_trusted_certificate

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_trusted_certificate` file;   |
|------------------------------------------------------------------------------------------|-----------------------------------|
| Default                                                                                  | —                                 |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                      |

Specifies a file with trusted CA certificates in the PEM format used to [verify](#m-ssl-verify-client) client certificates.

In contrast to the certificate set by [ssl_client_certificate](#m-ssl-client-certificate), the list of these certificates will not be sent to clients.





### ssl_verify_client

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_verify_client` `on` | `off` | `optional` | `optional_no_ca`;   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
| Default                                                                                  | `ssl_verify_client off;`                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                                                        |

Enables verification of client certificates. The verification result is passed in the `Auth-SSL-Verify` header of the [authentication](https://en.angie.software//angie/docs/configuration/modules/mail/mail_auth_http.md#m-auth-http) request. If an error occurs during client certificate verification or a client does not provide the required certificate, the connection is closed.

| `optional`       | requests the client certificate and verifies it if the certificate is present                                                                                                                                                                                                                                                                                                                                                                    |
|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `optional_no_ca` | requests the client certificate but does not require it to be signed by a trusted CA certificate. This is intended for use in cases when a service that is external to Angie performs the actual certificate verification. The contents of the certificate are accessible through requests [sent](https://en.angie.software//angie/docs/configuration/modules/mail/mail_auth_http.md#m-auth-http-pass-client-cert) to the authentication server. |





### ssl_verify_depth

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_verify_depth` number;   |
|------------------------------------------------------------------------------------------|------------------------------|
| Default                                                                                  | `ssl_verify_depth 1;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                 |

Sets the verification depth in the client certificates chain.





### starttls

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `starttls` `on` | `off` | `only`;   |
|------------------------------------------------------------------------------------------|-------------------------------------|
| Default                                                                                  | `starttls off;`                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                        |

| `on`   | allow usage of the STLS command for the POP3 and the STARTTLS command for the IMAP and SMTP;   |
|--------|------------------------------------------------------------------------------------------------|
| `off`  | deny usage of the STLS and STARTTLS commands;                                                  |
| `only` | require preliminary TLS transition.                                                            |


# https://en.angie.software/angie/docs/configuration/modules/google_perftools.md





# Google PerfTools Module

Enables profiling of Angie worker processes using [Google
Performance Tools](https://github.com/gperftools/gperftools). The module is
intended for Angie developers and allows them to analyze and optimize server
performance by providing detailed information about memory usage, CPU load, and
other performance metrics.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module isn't built
by default; it must be enabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--with-google_perftools_module`.

The module isn't included in packages and images from
[our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages).

#### NOTE
This module requires the
[gperftools](https://github.com/gperftools/gperftools) library.



## Configuration Example

```nginx
google_perftools_profiles /var/log/angie/perftools;
```

Profiles will be stored in files like
`/var/log/angie/perftools.`.



## Directives





### google_perftools_profiles

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `google_perftools_profiles` file prefix;   |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| Default                                                                                  | —                                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | main                                       |

Sets the filename prefix
where profiling information for the Angie worker process will be stored.
The worker process ID is appended at the end of the filename after a dot, for example:
`/var/log/angie/perftools.1234`.


# https://en.angie.software/angie/docs/configuration/modules/wasm.md



# WASM Module

The core module that implements basic WASM functionality in Angie: it includes
support for loading alternative runtimes and WASM modules, as well as
configuring their features and limits.

The other modules in this section extend this functionality, allowing you to
flexibly configure and optimize WASM capabilities for various scenarios and
requirements.

In our repositories, the module is built [dynamically](https://en.angie.software//angie/docs/installation/index.md#install-dynamicmodules)
and is available as a separate package named `angie-module-wasm`.



## Configuration Example

```none
# These directives load the core functionality
load_module modules/ngx_wasm_module.so;
load_module modules/ngx_wasm_core_module.so;

load_module modules/ngx_wasmtime_module.so;

# Available here: https://git.angie.software/web-server/angie-wasm
load_module modules/ngx_http_wasm_host_module.so;

events {

}

wasm_modules {

    #use wasmtime;

    load ngx_http_handler.wasm id=handler;
    load ngx_http_vars.wasm id=vars type=reactor;
}

http {

    wasm_var vars "ngx:wasi/var-utils#sum-entry" $rvar $arg_a $arg_b $arg_c $arg_d;

    server {

        listen *:8080;

        location / {

            return 200 "sum('$arg_a','$arg_b','$arg_c','$arg_d')=$rvar\n";
        }

        location /wasm {

            client_max_body_size 20M;
            wasm_content handler "ngx:wasi/http-handler-entry#handle-request";
        }
    }
}
```



## Directives





### load

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `load` file `id=`identifier [`fs=`host_path:guest_path]... [`api=`api]... [`type=``command` | `reactor`]   |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | —                                                                                                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | wasm_modules                                                                                               |

Loads a module from a disk file and assigns it a unique identifier
(required parameter). During loading, verification occurs to ensure the module
can be instantiated.

The directive supports the following parameters:

| `fs`   | Allows the guest to access a directory on the host.
The parameter can be specified multiple times for different directories.                                                                                                                                                                                                                                                       |
|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `api`  | Explicitly restricts the list of APIs allowed for the module by listing them.
If the module attempts to use unavailable APIs (not listed here),
an "API not found" error is returned.

By default, all APIs are available to the module.                                                                                                                               |
| `type` | Controls the lifecycle of the loaded module.

- In `command` mode, the machine executes once
  and its state is destroyed after execution.
- In `reactor` mode, the machine effectively runs indefinitely,
  allowing code to be executed multiple times.
  This requires careful memory management:
  if resources are not freed, memory leaks can occur. |





### wasm_modules

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `wasm_modules` { ... };   |
|------------------------------------------------------------------------------------------|---------------------------|
| Default                                                                                  | —                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | main                      |

A top-level directive that provides the configuration file context
in which WASM directives should be specified.
It can contain commands for loading WASM modules and configuring parameters
specific to a particular runtime.


# https://en.angie.software/angie/docs/configuration/modules/wasm/wasm_wamr.md



# WAMR

The module provides integration with [WebAssembly Micro Runtime](https://github.com/bytecodealliance/wasm-micro-runtime)
for executing WASM code,
adding a number of runtime-specific directives
to the [wasm_modules](https://en.angie.software//angie/docs/configuration/modules/wasm/index.md#wasm-modules) context.

In our repositories, the module is built
[dynamically](https://en.angie.software//angie/docs/installation/index.md#install-dynamicmodules)
and is available as a separate package named `angie-module-wamr`.



## Configuration Example

```nginx
wasm_modules {

    wamr_heap_size 16k;

    wamr_stack_size 16k;

    load fft_transform.wasm id=fft;
}
```



## Directives





### wamr_global_heap_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `wamr_global_heap_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `wamr_global_heap_size 1m;`                                                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | wasm_modules                                                                                                           |

Sets the heap [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units) for the entire WAMR runtime.





### wamr_heap_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `wamr_heap_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `wamr_heap_size 8k;`                                                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | wasm_modules                                                                                                    |

Sets the heap [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units) for an individual module instance.





### wamr_stack_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `wamr_stack_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `wamr_stack_size 8k;`                                                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | wasm_modules                                                                                                     |

Sets the stack [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units) for an individual module instance.


# https://en.angie.software/angie/docs/configuration/modules/wasm/wasm_wasmtime.md



# Wasmtime

The module provides integration with the [Wasmtime](https://wasmtime.dev/)
runtime for executing WASM code,
adding a number of runtime-specific directives
to the [wasm_modules](https://en.angie.software//angie/docs/configuration/modules/wasm/index.md#wasm-modules) context.

In our repositories, the module is built
[dynamically](https://en.angie.software//angie/docs/installation/index.md#install-dynamicmodules)
and is available as a separate package named `angie-module-wasmtime`.



## Configuration Example

```nginx
wasm_modules {

    wasmtime_stack_size 8k;

    wasmtime_enable_wasi on;

    load fft_transform.wasm id=fft;
}
```



## Directives





### wasmtime_enable_wasi

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `wasmtime_enable_wasi` `on` | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------------------|
| Default                                                                                  | `wasmtime_enable_wasi on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | wasm_modules                           |

Enables or disables the use of
[WebAssembly System Interface](https://github.com/WebAssembly/WASI) APIs
that provide basic [POSIX-like functionality](https://wasi.dev/interfaces)
to WASM modules running in Angie.

#### NOTE
Angie-specific APIs can be explicitly allowed using the [load](https://en.angie.software//angie/docs/configuration/modules/wasm/index.md#load) directive.





### wasmtime_stack_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `wasmtime_stack_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `wasmtime_stack_size 8k;`                                                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | wasm_modules                                                                                                         |

Sets the
[max_wasm_stack](https://docs.wasmtime.dev/api/wasmtime/struct.Config.html#method.max_wasm_stack)
value to the specified [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units),
thus limiting the maximum amount of stack space available for executing WASM code.


# https://en.angie.software/angie/docs/configuration/modules/external-modules.md





# Third-Party Modules

Below are popular third-party nginx-compatible modules
with brief descriptions.

| Module                                                                                                                                                                                                                                                                                                                                        | Description                                                                                                                                                                                                                                                                                                                            |
|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Auth JWT](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-jwt.md#external-auth-jwt)                                                                                                                                                                                                                        | Adds JWT authentication for clients.                                                                                                                                                                                                                                                                                                   |
| [Auth LDAP](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-ldap.md#external-ldap)                                                                                                                                                                                                                          | Adds support for LDAP authentication with multiple servers.                                                                                                                                                                                                                                                                            |
| [Auth PAM](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-pam.md#external-auth-pam)                                                                                                                                                                                                                        | Adds support for PAM authentication.                                                                                                                                                                                                                                                                                                   |
| [Auth SPNEGO](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-spnego.md#external-auth-spnego)                                                                                                                                                                                                               | Adds support for SPNEGO and GSSAPI.                                                                                                                                                                                                                                                                                                    |
| [Auth TOTP](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-totp.md#external-auth-totp)                                                                                                                                                                                                                     | Adds TOTP-based one-time password authentication.                                                                                                                                                                                                                                                                                      |
| [Brotli](https://en.angie.software//angie/docs/configuration/modules/external-modules/brotli.md#external-brotli)                                                                                                                                                                                                                              | Adds static and dynamic Brotli compression for responses.                                                                                                                                                                                                                                                                              |
| [Cache Purge](https://en.angie.software//angie/docs/configuration/modules/external-modules/cache-purge.md#external-cache-purge)                                                                                                                                                                                                               | Allows purging content from FastCGI, proxy, SCGI, and uWSGI caches.                                                                                                                                                                                                                                                                    |
| [CGI](https://en.angie.software//angie/docs/configuration/modules/external-modules/cgi.md#external-cgi)                                                                                                                                                                                                                                       | Adds support for CGI.                                                                                                                                                                                                                                                                                                                  |
| [Combined Upstreams](https://en.angie.software//angie/docs/configuration/modules/external-modules/combined-upstreams.md#external-combined-upstreams)                                                                                                                                                                                          | Allows combining multiple server groups into one.                                                                                                                                                                                                                                                                                      |
| [DAV Ext](https://en.angie.software//angie/docs/configuration/modules/external-modules/dav-ext.md#external-dav-ext)                                                                                                                                                                                                                           | Extends WebDAV support with PROPFIND and OPTIONS methods.                                                                                                                                                                                                                                                                              |
| [Dynamic Limit Req](https://en.angie.software//angie/docs/configuration/modules/external-modules/dynamic-limit-req.md#external-dynamic-limit-req)                                                                                                                                                                                             | Serves to dynamically block IP addresses and periodically unblock them.                                                                                                                                                                                                                                                                |
| [Echo](https://en.angie.software//angie/docs/configuration/modules/external-modules/echo.md#external-echo)                                                                                                                                                                                                                                    | Allows calling `echo`, `sleep`, `time`, `exec`
and other shell commands in the configuration file.                                                                                                                                                                                                                                 |
| [Enhanced Memcached](https://en.angie.software//angie/docs/configuration/modules/external-modules/enhanced-memcached.md#external-enhanced-memcached)                                                                                                                                                                                          | Extends the capabilities of the built-in [Memcached](https://en.angie.software//angie/docs/configuration/modules/http/http_memcached.md#http-memcached) module.                                                                                                                                                                        |
| [Eval](https://en.angie.software//angie/docs/configuration/modules/external-modules/eval.md#external-eval)                                                                                                                                                                                                                                    | Allows saving response bodies of subrequests into variables.                                                                                                                                                                                                                                                                           |
| [GeoIP2](https://en.angie.software//angie/docs/configuration/modules/external-modules/geoip2.md#external-geoip2)                                                                                                                                                                                                                              | Adds geolocation search in MaxMind GeoIP2 databases.                                                                                                                                                                                                                                                                                   |
| [Headers More](https://en.angie.software//angie/docs/configuration/modules/external-modules/headers-more.md#external-headers-more)                                                                                                                                                                                                            | Allows setting and clearing request and response headers.                                                                                                                                                                                                                                                                              |
| [HTTP Auth RADIUS](https://en.angie.software//angie/docs/configuration/modules/external-modules/http-auth-radius.md#external-http-auth-radius)                                                                                                                                                                                                | Adds support for Radius.                                                                                                                                                                                                                                                                                                               |
| [JWT](https://en.angie.software//angie/docs/configuration/modules/external-modules/jwt.md#external-jwt)                                                                                                                                                                                                                                       | Lightweight alternative to [Auth JWT](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-jwt.md#external-auth-jwt).                                                                                                                                                                                     |
| [Keyval](https://en.angie.software//angie/docs/configuration/modules/external-modules/keyval.md#external-keyval)                                                                                                                                                                                                                              | Allows using variables with values from key-value pairs.                                                                                                                                                                                                                                                                               |
| [Lua](https://en.angie.software//angie/docs/configuration/modules/external-modules/lua.md#external-lua):
`http_lua_module`,
`stream_lua_module`                                                                                                                                                                                       | Allow using the Lua language in Angie configuration
in the `http` and `stream` contexts, respectively.                                                                                                                                                                                                                             |
| [ModSecurity](https://en.angie.software//angie/docs/configuration/modules/external-modules/modsecurity.md#external-modsec)                                                                                                                                                                                                                    | Adds a connector for using ModSecurity rules.                                                                                                                                                                                                                                                                                          |
| [NJS](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs):
[http_js](https://en.angie.software//angie/docs/configuration/modules/external-modules/http_js.md#http-js),
[stream_js](https://en.angie.software//angie/docs/configuration/modules/external-modules/stream_js.md#stream-js) | Allow using njs, a subset of the JavaScript language,
in Angie configuration
in the `http` and `stream` contexts, respectively.

Also available is a lightweight version of the package named
`...-njs-light`; however, it is incompatible with the regular version
and cannot be used simultaneously with it. |
| [NDK](https://en.angie.software//angie/docs/configuration/modules/external-modules/ndk.md#external-ndk)                                                                                                                                                                                                                                       | Adds the Nginx Development Kit (NDK) for developing new modules.                                                                                                                                                                                                                                                                       |
| [OpenTracing](https://en.angie.software//angie/docs/configuration/modules/external-modules/opentracing.md#external-opentracing)                                                                                                                                                                                                               | Adds distributed OpenTracing request tracing in Angie;
contains plugins for exporting data to Zipkin and DataDog.                                                                                                                                                                                                                  |
| [OpenTelemetry](https://en.angie.software//angie/docs/configuration/modules/external-modules/otel.md#external-otel)                                                                                                                                                                                                                           | Allows sending telemetry data to the OpenTelemetry collector.                                                                                                                                                                                                                                                                          |
| [PostgreSQL](https://en.angie.software//angie/docs/configuration/modules/external-modules/postgres.md#external-postgres)                                                                                                                                                                                                                      | Includes direct support for PostgreSQL databases.                                                                                                                                                                                                                                                                                      |
| [Redis2](https://en.angie.software//angie/docs/configuration/modules/external-modules/redis2.md#external-redis2)                                                                                                                                                                                                                              | Includes support for Redis 2.0 for HTTP upstreams.                                                                                                                                                                                                                                                                                     |
| [RTMP](https://en.angie.software//angie/docs/configuration/modules/external-modules/rtmp.md#external-rtmp)                                                                                                                                                                                                                                    | Includes support for RTMP for streaming and video-on-demand broadcasts.                                                                                                                                                                                                                                                                |
| [Set Misc](https://en.angie.software//angie/docs/configuration/modules/external-modules/set-misc.md#external-set-misc)                                                                                                                                                                                                                        | Adds various set_xxx directives to the
[Rewrite](https://en.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#http-rewrite) module.                                                                                                                                                                            |
| [Subs](https://en.angie.software//angie/docs/configuration/modules/external-modules/subs.md#external-subs)                                                                                                                                                                                                                                    | Allows replacing strings in HTTP response bodies using regular expressions.                                                                                                                                                                                                                                                            |
| [TestCookie](https://en.angie.software//angie/docs/configuration/modules/external-modules/testcookie.md#external-testcookie)                                                                                                                                                                                                                  | Helps combat bots
using a "challenge-response" mechanism based on cookies.                                                                                                                                                                                                                                                         |
| [UnBrotli](https://en.angie.software//angie/docs/configuration/modules/external-modules/unbrotli.md#external-unbrotli)                                                                                                                                                                                                                        | Unpacks responses with `Content-Encoding: br`
for clients that do not support Brotli encoding.                                                                                                                                                                                                                                     |
| [Upload](https://en.angie.software//angie/docs/configuration/modules/external-modules/upload.md#external-upload)                                                                                                                                                                                                                              | Adds `multipart/form-data` (RFC 1867) encoding for file uploads
from the client, including resume capability.                                                                                                                                                                                                                      |
| [VOD](https://en.angie.software//angie/docs/configuration/modules/external-modules/vod.md#external-vod)                                                                                                                                                                                                                                       | Allows repackaging MP4 files for streaming via HLS, HDS, MSS, and DASH.                                                                                                                                                                                                                                                                |
| [VTS](https://en.angie.software//angie/docs/configuration/modules/external-modules/vts.md#external-vts):
`module-vts`,
`module-sts`,
`module-stream-sts`                                                                                                                                                                          | Include the three listed modules for traffic monitoring.                                                                                                                                                                                                                                                                               |
| [ZIP](https://en.angie.software//angie/docs/configuration/modules/external-modules/zip.md#external-zip)                                                                                                                                                                                                                                       | Includes dynamic ZIP archive packaging.                                                                                                                                                                                                                                                                                                |
| [Zstd](https://en.angie.software//angie/docs/configuration/modules/external-modules/zstd.md#external-zstd)                                                                                                                                                                                                                                    | Includes Zstandard compression.                                                                                                                                                                                                                                                                                                        |


# https://en.angie.software/angie/docs/configuration/modules/external-modules/auth-jwt.md





# Auth JWT

The module implements client authorization by verifying the provided JSON Web Token (JWT) using the specified keys.

- Supports JSON Web Signature (JWS).
- Can be used for authentication via OpenID Connect.



## Installation

To [install](https://en.angie.software//angie/docs/installation/index.md#install-packages) the module, use one of the following packages:

- Angie: `angie-module-auth-jwt`
- Angie PRO: `angie-pro-module-auth-jwt`



## Loading the Module

Load the module in the `main{}` context:

```nginx
load_module modules/ngx_http_auth_jwt_module.so;
```



## Configuration Example

```nginx
location / {
    auth_jwt          "closed site";
    auth_jwt_key_file conf/keys.json;
}
```

A complete configuration example is available at:
[https://github.com/kjdev/nginx-auth-jwt/tree/main/example](https://github.com/kjdev/nginx-auth-jwt/tree/main/example)



## Additional Information

**Version:** 0.14.2

Detailed documentation and source code are available at:
[https://github.com/kjdev/nginx-auth-jwt](https://github.com/kjdev/nginx-auth-jwt)


# https://en.angie.software/angie/docs/configuration/modules/external-modules/auth-ldap.md





# Auth LDAP

The LDAP module supports authentication across multiple LDAP servers.



## Installation

To [install](https://en.angie.software//angie/docs/installation/index.md#install-packages) the module, use one of the
following packages:

- Angie: `angie-module-auth-ldap`
- Angie PRO: `angie-pro-module-auth-ldap`



## Loading the Module

Load the module in the `main{}` context:

```nginx
load_module modules/ngx_http_auth_ldap_module.so;
```



## Configuration Example

```nginx
http {
    ldap_server test1 {
        url ldap://192.168.0.1:3268/DC=test,DC=local?sAMAccountName?sub?(objectClass=person);
        binddn "TEST\\LDAPUSER";
        binddn_passwd LDAPPASSWORD;
        group_attribute uniquemember;
        group_attribute_is_dn on;
        require valid_user;
    }

    ldap_server test2 {
        url ldap://192.168.0.2:3268/DC=test,DC=local?sAMAccountName?sub?(objectClass=person);
        binddn "TEST\\LDAPUSER";
        binddn_passwd LDAPPASSWORD;
        group_attribute uniquemember;
        group_attribute_is_dn on;
        require valid_user;
    }

    server {
        listen       8000;
        server_name  localhost;

        auth_ldap "Forbidden";
        auth_ldap_servers test1;
        auth_ldap_servers test2;

        location / {
            root   html;
            index  index.html index.htm;
        }
    }
}
```



## Additional Information

**Version:** 241200e

Detailed documentation and source code are available at:
[https://github.com/kvspb/nginx-auth-ldap](https://github.com/kvspb/nginx-auth-ldap)


# https://en.angie.software/angie/docs/configuration/modules/external-modules/auth-pam.md





# Auth PAM

The module adds support for PAM authentication.



## Installation

To [install](https://en.angie.software//angie/docs/installation/index.md#install-packages) the module, use one of the following packages:

- Angie: `angie-module-auth-pam`
- Angie PRO: `angie-pro-module-auth-pam`



## Loading the Module

Load the module in the `main{}` context:

```nginx
load_module modules/ngx_http_auth_pam_module.so;
```



## Configuration Example

```nginx
location /secure {
    auth_pam              "Secure Zone";
    auth_pam_service_name "angie";
}
```

As an example, to authenticate users on an LDAP server (using the `pam_ldap.so` module), the `/etc/pam.d/angie` file may contain the following:

```none
auth    required     /lib/security/pam_ldap.so
account required     /lib/security/pam_ldap.so
```



## Additional Information

**Version:** v1.5.5

Detailed documentation and source code are available at:
[https://github.com/sto/ngx_http_auth_pam_module](https://github.com/sto/ngx_http_auth_pam_module)


# https://en.angie.software/angie/docs/configuration/modules/external-modules/auth-spnego.md





# Auth SPNEGO

The module provides support for SPNEGO.
Currently, only Kerberos authentication via GSSAPI is supported.



## Installation

To [install](https://en.angie.software//angie/docs/installation/index.md#install-packages) the module, use one of the
following packages:

- Angie: `angie-module-auth-spnego`
- Angie PRO: `angie-pro-module-auth-spnego`



## Loading the Module

Load the module in the `main{}` context:

```nginx
load_module modules/ngx_http_auth_spnego_module.so;
```



## Additional Information

**Version:** v1.1.3

Detailed documentation and source code are available at:
[https://github.com/stnoonan/spnego-http-auth-nginx-module](https://github.com/stnoonan/spnego-http-auth-nginx-module)


# https://en.angie.software/angie/docs/configuration/modules/external-modules/auth-totp.md





# Auth TOTP

The module implements the time-based one-time password (TOTP) algorithm
and provides short-lived one-time passwords.

Features:

- Standard HTTP authentication using TOTP.
- Tracking authenticated clients via cookies after TOTP expiration.
- Configurable secret, time seed, time step, and truncation length for TOTP generation.
- Configurable time window for TOTP verification.



## Installation

To [install](https://en.angie.software//angie/docs/installation/index.md#install-packages) the module, use one of the following packages:

- Angie: `angie-module-auth-totp`
- Angie PRO: `angie-pro-module-auth-totp`



## Loading the Module

To use the module, load it in the `main{}` context:

```nginx
load_module modules/ngx_http_auth_totp_module.so;
```



## Configuration Example

```nginx
server {
    listen 80;

    location /protected {
        auth_totp_realm "Protected";
        auth_totp_file /etc/angie/totp.conf;
        auth_totp_length 8;
        auth_totp_reuse off;
        auth_totp_skew 1;
        auth_totp_step 1m;
        auth_totp_cookie "totp-session";
        auth_totp_expiry 1d;
    }
}
```



## Additional Information

**Version:** 1.2.0

Detailed documentation and source code are available at:
[https://github.com/61131/nginx-http-auth-totp](https://github.com/61131/nginx-http-auth-totp)


# https://en.angie.software/angie/docs/configuration/modules/external-modules/brotli.md





# Brotli

This is a set of two modules:

- `ngx_brotli_filter` — used for on-the-fly compression of responses.
- `ngx_brotli_static` — used for serving pre-compressed files.



## Installation

To [install](https://en.angie.software//angie/docs/installation/index.md#install-packages) the module, use one of the following packages:

- Angie: `angie-module-brotli`
- Angie PRO: `angie-pro-module-brotli`



## Loading Modules

Loading the modules in the `main{}` context:

```nginx
load_module modules/ngx_http_brotli_filter_module.so;
load_module modules/ngx_http_brotli_static_module.so;
```



## Example Configuration for Dynamic Compression

```nginx
server {
    listen 80 default_server;
    brotli on;
    brotli_comp_level 1;
    brotli_types text/plain text/css;

    location / {
        root /usr/share/angie/html;
        index index.html;
    }
}
```



## Preparing for Demonstration

First, let's place the test file `war-and-peace.txt`:

```console
$ ls -l /usr/share/angie/html/

  total 3292
  -rw-r--r-- 1 root root     497 Feb 13 07:40 50x.html
  -rw-r--r-- 1 root root     543 Feb 13 07:40 index.html
  -rw-r--r-- 1 root root 3359405 Feb 26 12:47 war-and-peace.txt
```

```console
$ mkdir tmp
```

Request for compressed file:

```console
$ curl -s -H 'Accept-encoding: br' -o tmp/war-and-peace.br localhost/war-and-peace.txt
```

```console
$ ls -l tmp/

  total 1092
  -rw-r--r-- 1 asv asv 1115616 Feb 26 16:52 war-and-peace.br
```



## Example Configuration for Serving Pre-compressed Files

```nginx
server {
    listen 80 default_server;

    brotli_static on;
    brotli_types text/plain text/css;

    location / {
        root /usr/share/angie/html;
        index index.html;
    }
}
```



## Moving the Pre-compressed File

```console
$ sudo mv tmp/war-and-peace.br /usr/share/angie/html/war-and-peace.txt.br

$ ls -l /usr/share/angie/html/

  total 4384
  -rw-r--r-- 1 root root     497 Feb 13 07:40 50x.html
  -rw-r--r-- 1 root root     543 Feb 13 07:40 index.html
  -rw-r--r-- 1 root root 3359405 Feb 26 12:47 war-and-peace.txt
  -rw-r--r-- 1 root root 1115616 Feb 26 16:57 war-and-peace.txt.br
```

Request for compressed file:

```console
$ curl -s -H 'Accept-encoding: br' -o tmp/war-and-peace.br localhost/war-and-peace.txt
```

```console
$ ls -l tmp/

  total 1092
  -rw-r--r-- 1 asv asv 1115616 Feb 26 17:13 war-and-peace.br
```



## Combining Dynamic and Static Compression

In one configuration, it is possible to combine the use of dynamic compression
(`brotli on`) and static selection (`brotli_static on`). In this case, the system will first look for the corresponding static compressed file. If such a file is not found, dynamic compression of the file specified in the request will occur.



## Additional Information

**Version:** v1.0.0rc

Full documentation of directives and source code is available at:
[https://github.com/google/ngx_brotli](https://github.com/google/ngx_brotli).


# https://en.angie.software/angie/docs/configuration/modules/external-modules/cache-purge.md





# Cache Purge

Allows clearing the cache content.



## Installation

To [install](https://en.angie.software//angie/docs/installation/index.md#install-packages) the module, use one of the following packages:

- Angie: `angie-module-cache-purge`
- Angie PRO: `angie-pro-module-cache-purge`



## Loading the Module

Loading the module in the `main{}` context:

```nginx
load_module modules/ngx_http_cache_purge_module.so;
```



## Configuration Example

```nginx
log_format test_cache '[$time_local] "$request" '
                      '$status $body_bytes_sent rt="$request_time" '
                      'ucs="$upstream_cache_status" us="$upstream_status" '
                      'ubr=$upstream_bytes_received';

proxy_cache_path /var/cache/angie/cache keys_zone=cache_zone:10m;

server {
    listen 80 default_server;

    location / {
        access_log /var/log/angie/cache-access.log test_cache;
        proxy_pass http://127.0.0.1:8080;

        proxy_cache cache_zone;
        proxy_cache_valid 10m;
        proxy_cache_key $uri$is_args$args;
        proxy_cache_purge PURGE from 127.0.0.1;
    }
}
```



## Preparing for Demonstration

Requesting a file from the server:

```console
$ curl -s -o testf1.txt http://127.0.0.1/storage/testf1.txt
```

Checking the cache (MISS — file not found in cache):

```console
[05/Mar/2025:17:44:24 +0300] "GET /storage/testf1.txt HTTP/1.1" 200 519 rt="0.001" ucs="MISS" us="200" ubr=752
```

Re-requesting (HIT — file served from cache):

```console
$ curl -s -o testf1.txt http://127.0.0.1/storage/testf1.txt
```

```console
[05/Mar/2025:17:46:02 +0300] "GET /storage/testf1.txt HTTP/1.1" 200 519 rt="0.000" ucs="HIT" us="-" ubr=-
```



## Clearing the Cache

```console
$ curl -X PURGE http://127.0.0.1/storage/*

Successful purgeSuccessful purge
Key : /storage/*
```

Requesting a file after cache clearing (MISS — file loaded again):

```console
$ curl -s -o testf1.txt http://127.0.0.1/storage/testf1.txt
```

```console
[05/Mar/2025:17:52:05 +0300] "GET /storage/testf1.txt HTTP/1.1" 200 519 rt="0.002" ucs="MISS" us="200" ubr=752
```



## Configuration Example for a Separate Cache Clearing Location

```nginx
proxy_cache_path /var/cache/angie/cache keys_zone=cache_zone:10m;

map $uri $wpurgeuri {
    "~/purge(?/.*)" $wpurge;
    default $uri;
}

server {
    listen 80 default_server;

    location / {
        access_log /var/log/angie/cache-access.log test_cache;
        proxy_pass http://127.0.0.1:8080;

        proxy_cache cache_zone;
        proxy_cache_valid 10m;
        proxy_cache_key $uri$is_args$args;
    }

    location /purge {
        allow 127.0.0.1;
        deny all;
        proxy_cache_purge cache_zone $wpurgeuri$is_args$args;
    }
}
```

Request for clearing the cache in this case:

```console
$ curl -X PURGE http://127.0.0.1/purge/storage/*
```



## Additional Information

**Version:** 3.0.2

Full documentation of directives and source code is available at:
[https://github.com/nginx-modules/ngx_cache_purge](https://github.com/nginx-modules/ngx_cache_purge)


# https://en.angie.software/angie/docs/configuration/modules/external-modules/cgi.md





# CGI

The module adds support for CGI.

It is important to note that CGI **is not** suitable for:

- high QPS;
- heavy traffic;
- high concurrency.



## Installation

To [install](https://en.angie.software//angie/docs/installation/index.md#install-packages) the module, use one of the
following packages:

- Angie: `angie-module-cgi`
- Angie PRO: `angie-pro-module-cgi`



## Loading the Module

To load the module in the `main{}` context:

```nginx
load_module modules/ngx_http_cgi_module.so;
```



## Configuration Example

```nginx
server {
    listen 80;

    root /usr/share/angie/html;
    index index.html index.htm;

    location /cgi {
        alias /usr/share/angie/cgi-bin;
        cgi on;
    }
}
```



## Test Script

An example test executable script `test.sh`:

```bash
#!/bin/sh
echo "Content-Type: text/plain" # Add header to the response
echo "" # Separator between headers and body of the response

# Environment variables
echo "query string: $QUERY_STRING"
echo "server addr: $SERVER_ADDR"
echo "server port: $SERVER_PORT"

# Request headers via environment variables
echo "http host: $HTTP_HOST"
echo "http accept: $HTTP_ACCEPT"
echo "http Some-Field: $HTTP_SOME_FIELD"

body=$(cat) # Reads the request body into a variable
echo "Request body: $body"
```



## Placing the Script

According to the configuration, the script must be placed in the
`/usr/share/angie/cgi-bin/` directory.
The file must have read and execute permissions.



## Example of Request Execution

```console
$ curl  -H 'Some-Field:some text' -d '{"key1":"value1", "key2":"value2"}' -i \
  'http://127.0.0.1/cgi/hello.sh?a=valueA&b=valueB'

HTTP/1.1 200 OK
Server: Angie/1.12.1
Date: Fri, 17 Jul 2026 19:15:35 GMT
Transfer-Encoding: chunked
Connection: keep-alive
Content-Type: text/plain

query string: a=valueA&b=valueB
server addr: 127.0.0.1
server port: 80
http host: 127.0.0.1
http accept: */*
http Some-Field: some text
Request body: {"key1":"value1", "key2":"value2"}
```



## Additional Information

**Version:** v0.15

Detailed documentation and source code are available at:
[https://github.com/pjincz/nginx-cgi](https://github.com/pjincz/nginx-cgi)


# https://en.angie.software/angie/docs/configuration/modules/external-modules/combined-upstreams.md





# Combined Upstreams

The module allows combining multiple server groups into one.

It introduces the `add_upstream`, `combine_server_singlets`, and
`extend_single_peers` directives available within `upstream`
configuration blocks, as well as a new `upstrand` configuration block for
creating higher-level `upstream` blocks. In addition, it introduces the
`dynamic_upstrand` directive for selecting `upstream` blocks at runtime.



## Installation

To [install](https://en.angie.software//angie/docs/installation/index.md#install-packages) the module, use one of the following packages:

- Angie: `angie-module-combined-upstreams`
- Angie PRO: `angie-pro-module-combined-upstreams`



## Loading the Module

To use the module, load it in the `main{}` context:

```nginx
load_module modules/ngx_http_combined_upstreams_module.so;
```



## Additional Information

**Version:** 2.3.1

Detailed documentation and source code are available at:
[https://github.com/lyokha/nginx-combined-upstreams-module](https://github.com/lyokha/nginx-combined-upstreams-module)

Configuration examples and a detailed breakdown of the module directives:

- [http://lin-techdet.blogspot.com/2011/10/nginx.html](http://lin-techdet.blogspot.com/2011/10/nginx.html)
- [http://lin-techdet.blogspot.com/2015/12/nginx.html](http://lin-techdet.blogspot.com/2015/12/nginx.html)


# https://en.angie.software/angie/docs/configuration/modules/external-modules/dav-ext.md





# DAV Ext

This module extends WebDAV support with the PROPFIND, OPTIONS, LOCK, and UNLOCK methods.

The standard [DAV](https://en.angie.software//angie/docs/configuration/modules/http/http_dav.md#http-dav) module provides a partial implementation of
WebDAV and supports only the GET, HEAD, PUT, DELETE, MKCOL, COPY, and MOVE methods.
For full WebDAV support, you need to enable the standard
`http_dav_module` module, as well as this module for the missing methods.



## Installation

To [install](https://en.angie.software//angie/docs/installation/index.md#install-packages) the module, use one of the
following packages:

- Angie: `angie-module-dav-ext`
- Angie PRO: `angie-pro-module-dav-ext`



## Loading the Module

Load the module in the `main{}` context:

```nginx
load_module modules/ngx_http_dav_ext_module.so;
```



## Configuration Example

```nginx
dav_ext_lock_zone zone=lock_zone:10m;
server {
    listen 80 default_server;

    location / {
        root /usr/share/angie/html;

        dav_methods PUT DELETE MKCOL COPY MOVE;
        dav_ext_methods PROPFIND OPTIONS LOCK UNLOCK;
        dav_ext_lock zone=lock_zone;
    }
}
```



## Request Execution Examples

Uploading a file to the server:

```console
$ curl -i -X PUT -d @testf1.txt http://127.0.0.1/testf1.txt
HTTP/1.1 201 Created
Server: Angie/1.12.1
Date: Fri, 17 Jul 2026 19:15:35 GMT
Content-Length: 0
Location: http://127.0.0.1/testf1.txt
Connection: keep-alive
```

Overwriting the same file:

```console
$ curl -i -X PUT -d @testf1.txt http://127.0.0.1/testf1.txt
HTTP/1.1 204 No Content
Server: Angie/1.12.1
Date: Fri, 17 Jul 2026 19:15:35 GMT
Connection: keep-alive
```

Locking the file from being overwritten:

```console
$ curl -i -X LOCK http://127.0.0.1/testf1.txt
HTTP/1.1 200 OK
Server: Angie/1.12.1
Date: Fri, 17 Jul 2026 19:15:35 GMT
Content-Type: text/xml; charset=utf-8
Content-Length: 392
Connection: keep-alive
Lock-Token: 
```

Attempting to overwrite the file:

```console
$ curl -i -X PUT -d @testf1.txt http://127.0.0.1/testf1.txt
HTTP/1.1 423
Server: Angie/1.12.1
Date: Fri, 17 Jul 2026 19:15:35 GMT
Content-Length: 0
Connection: keep-alive
```

The file is locked. Unlocking the file:

```console
$ curl -i -X UNLOCK -H 'Lock-Token: ' http://127.0.0.1/testf1.txt
HTTP/1.1 204 No Content
Server: Angie/1.12.1
Date: Fri, 17 Jul 2026 19:15:35 GMT
Connection: keep-alive
```

Overwriting the file:

```console
$ curl -i -X PUT -d @testf1.txt http://127.0.0.1/testf1.txt
HTTP/1.1 204 No Content
Server: Angie/1.12.1
Date: Fri, 17 Jul 2026 19:15:35 GMT
Connection: keep-alive
```

The file has been successfully unlocked and overwritten.



## Additional Information

**Version:** v4.0.1

Detailed documentation and source code are available at:
[https://github.com/arut/nginx-dav-ext-module](https://github.com/arut/nginx-dav-ext-module)


# https://en.angie.software/angie/docs/configuration/modules/external-modules/dynamic-limit-req.md





# Dynamic Limit Req

The module provides dynamic blocking of IP addresses when request limits are exceeded,
and automatically removes the block after the specified time.



## Loading the Module

Load the module in the `main{}` context:

```nginx
load_module modules/ngx_http_dynamic_limit_req_module.so;
```



## Configuration Example

```nginx
http {
    include       mime.types;
    default_type  application/octet-stream;
    sendfile        on;
    keepalive_timeout  65;

    dynamic_limit_req_zone $binary_remote_addr zone=one:10m rate=100r/s redis=127.0.0.1 block_second=300;
    dynamic_limit_req_zone $binary_remote_addr zone=two:10m rate=50r/s redis=127.0.0.1 block_second=600;
    dynamic_limit_req_zone $binary_remote_addr zone=sms:5m rate=5r/m redis=127.0.0.1 block_second=1800;

    server {
        listen       80;
        server_name  localhost;

        location / {
            if ($http_x_forwarded_for) {
                return 400;
            }

            root   html;
            index  index.html index.htm;

            dynamic_limit_req zone=one burst=100 nodelay;
            dynamic_limit_req_status 403;
        }

        error_page   403 500 502 503 504  /50x.html;

        location = /50x.html {
            root   html;
        }
    }

    server {
        listen       80;
        server_name  localhost2;

        location / {
            root   html;
            index  index.html index.htm;

            set $flag 0;
            if ($document_uri ~* "regist") {
                set $flag "${flag}1";
            }
            if ($request_method = POST) {
                set $flag "${flag}2";
            }
            if ($flag = "012") {
                dynamic_limit_req zone=sms burst=3 nodelay;
                dynamic_limit_req_status 403;
            }

            if ($document_uri ~* "getSmsVerifyCode.do") {
                dynamic_limit_req zone=sms burst=5 nodelay;
                dynamic_limit_req_status 444;
            }

            dynamic_limit_req zone=two burst=50 nodelay;
            dynamic_limit_req_status 403;
        }

        error_page   403 502 503 504  /50x.html;

        location = /50x.html {
            root   html;
        }
    }
}
```



## Additional Information

**Version:** 1.9.3

Detailed documentation and source code are available at:
[https://github.com/limithit/ngx_dynamic_limit_req_module](https://github.com/limithit/ngx_dynamic_limit_req_module)


# https://en.angie.software/angie/docs/configuration/modules/external-modules/echo.md





# Echo

The module adds `echo`, `sleep`, `time`, `exec`, and
other shell-style functions.



## Installation

To [install](https://en.angie.software//angie/docs/installation/index.md#install-packages) the module, use one of the
following packages:

- Angie: `angie-module-echo`
- Angie PRO: `angie-pro-module-echo`



## Loading the Module

To work with the module, it must be loaded in the `main{}` context:

```nginx
load_module modules/ngx_http_echo_module.so;
```



## Configuration Example

```nginx
server {
    listen       80;
    server_name  localhost;

    location /echo {
        echo_before_body 'These lines are inserted';
        echo_before_body 'by the echo_before_body directive';
        echo_after_body 'These lines are added';
        echo_after_body 'by the echo_after_body directive';
        proxy_pass $scheme://127.0.0.1:$server_port$request_uri/more;
    }

    location /echo/more {
        set $val 'value';
        echo '======== Start backend answer =========';
        echo 'Backend answer body';
        echo "val is set on $val";
        echo '======== End backend answer ===========';
    }

    location /echo_with_sleep {
        echo hello;
        echo_flush;
        echo_sleep   2.5;
        echo world;
    }

    location /dup {
        echo_duplicate 3 "--";
        echo_duplicate 1 " END ";
        echo_duplicate 3 "--";
        echo;
    }

    location /subr {
        echo_reset_timer;
        echo_location /sub1;
        echo_location /sub2;
        echo "took $echo_timer_elapsed sec for total.";
    }

    location /subr_async {
        echo_reset_timer;
        echo_location_async /sub1;
        echo_location_async /sub2;
        echo "took $echo_timer_elapsed sec for total.";
    }

    location /sub1 {
        echo_sleep 2;
        echo hello;
    }

    location /sub2 {
        echo_sleep 1;
        echo world;
    }
}
```



## Demonstration

Let's make a few requests to demonstrate the module's functionality.

```console
$ curl localhost/echo

  These lines are inserted
  by the echo_before_body directive
  ======== Start backend answer =========
  Backend answer body
  val is set on value
  ======== End backend answer ==========
  These lines are added
  by the echo_after_body directive
```

```console
$ curl localhost/echo_with_sleep

  hello
  world
```

The strings "hello" and "world" will appear with an interval of 2.5 seconds.

```console
$ curl localhost/dup
------ END ------
```

```console
$ time curl localhost/subr

  hello
  world
  took 3.004 sec for total.

  real    0m3.027s
  user    0m0.015s
  sys     0m0.007s
```

```console
$ time curl localhost/subr_async

  hello
  world
  took 0.000 sec for total.

  real    0m2.023s
  user    0m0.001s
  sys     0m0.020s
```



## Additional Information

**Version:** v0.64

Detailed documentation and source code are available at:
[https://github.com/openresty/echo-nginx-module](https://github.com/openresty/echo-nginx-module).


# https://en.angie.software/angie/docs/configuration/modules/external-modules/enhanced-memcached.md





# Enhanced Memcached

This module extends the capabilities of the built-in [Memcached](https://en.angie.software//angie/docs/configuration/modules/http/http_memcached.md#http-memcached) module, allowing you to add and remove key-value data on the memcached server.



## Installation

To [install](https://en.angie.software//angie/docs/installation/index.md#install-packages) the module, use one of the following packages:

- Angie: `angie-module-enhanced-memcached`
- Angie PRO: `angie-pro-module-enhanced-memcached`



## Loading the Module

Load the module in the `main{}` context:

```nginx
load_module modules/ngx_http_enhanced_memcached_module.so;
```



## Configuration Example

```nginx
upstream memcached_upstream {
    server 127.0.0.1:11211;
}

server {
    listen 80;
    server_name localhost;

    location / {
        set $enhanced_memcached_key "$request_uri";
        enhanced_memcached_allow_put on;
        enhanced_memcached_allow_delete on;
        enhanced_memcached_pass memcached_upstream;
    }

    location /stats {
        enhanced_memcached_stats on;
        enhanced_memcached_pass memcached_upstream;
        access_log off;
    }

    location /flush {
        enhanced_memcached_flush on;
        enhanced_memcached_pass memcached_upstream;
    }
}
```



## Request Examples

Adding a key `key1` with the value `key1 value`:

```console
$ curl -X PUT -d 'key1 value' http://127.0.0.1/key1
STORED
```

Retrieving the value of `key1`:

```console
$ curl http://127.0.0.1/key1
key1 value
```

Deleting the data with key `key1`:

```console
$ curl -X DELETE http://127.0.0.1/key1
DELETED
```

Outputting memcached statistics:

```console
$ curl http://127.0.0.1/stats
```

Clearing all data:

```console
$ curl http://127.0.0.1/flush
```



## Additional Information

**Version:** v0.3

Detailed documentation and source code are available at:
[https://github.com/bpaquet/ngx_http_enhanced_memcached_module](https://github.com/bpaquet/ngx_http_enhanced_memcached_module)


# https://en.angie.software/angie/docs/configuration/modules/external-modules/eval.md





# Eval

The module allows saving subrequest response bodies in variables.



## Installation

To [install](https://en.angie.software//angie/docs/installation/index.md#install-packages) the module, use one of the
following packages:

- Angie: `angie-module-eval`
- Angie PRO: `angie-pro-module-eval`



## Loading the Module

Load the module in the `main{}` context:

```nginx
load_module modules/ngx_http_eval_module.so;
```



## Example Configuration

```nginx
server {
    listen 80;
    server_name localhost;

    location / {
        eval_subrequest_in_memory off;
        eval_override_content_type text/plain;
        eval_buffer_size 4k;
        eval $res {
            rewrite ^(/eval_.*/)(.*)$  /$2 break;
            proxy_pass http://127.0.0.1:8081;
        }

        if ($res ~ "access denied") {
            return 403 $res\n;
        }

        proxy_pass http://127.0.0.1:8082;
    }
}

server {
    listen 8081;

    if ($arg_user != 'Legal') {
        return 403 "access denied";
    }
    return 200 OK;
}

server {
    listen 8082;

    location / {
        root /usr/share/angie/html;
    }
}
```



## Additional Information

**Version:** 2016.06.10

Detailed documentation and source code are available at:
[https://github.com/openresty/nginx-eval-module](https://github.com/openresty/nginx-eval-module)


# https://en.angie.software/angie/docs/configuration/modules/external-modules/geoip2.md





# GeoIP2

The GeoIP2 module implements lookup in MaxMind GeoIP2 databases by the client's IP address (by default) or by the value of a specific variable. It supports both IPv4 and IPv6.



## Installation

To [install](https://en.angie.software//angie/docs/installation/index.md#install-packages) the module, use one of the following packages:

- Angie: `angie-module-geoip2`
- Angie PRO: `angie-pro-module-geoip2`



## Loading the Module

To work with the module, it must be loaded in the `main{}` context:

```nginx
load_module modules/ngx_http_geoip2_module.so;    # for use in the http{} block
load_module modules/ngx_stream_geoip2_module.so;  # for use in the stream{} context
```

In the configuration example below, in addition to the directives of the module itself, the directives of the [Echo](https://en.angie.software//angie/docs/configuration/modules/external-modules/echo.md#external-echo) module are also used:

```nginx
load_module modules/ngx_http_echo_module.so;
```



## Configuration Example

```nginx
http {
    geoip2 /var/lib/GeoIP/GeoLite2-Country.mmdb {
        auto_reload 1h;
        $geoip2_country_code default=RU source=$http_x_forwarded_for country iso_code;
        $geoip2_country_name source=$http_x_forwarded_for country names ru;
    }

    log_format with_geoip '$server_port $remote_addr - $remote_user [$time_local] "$request" '
                           '$status $body_bytes_sent "$http_referer" '
                           '"$http_user_agent" "$http_x_forwarded_for" "$http_host" '
                           'country="$geoip2_country_code"';

    map $geoip2_country_code $denied {
        PL "1";
        QA "1";
    }

    server {
        listen 80;
        root /usr/share/angie/html;
        index index.html index.htm;
        access_log /var/log/angie/geoip_access.log with_geoip;

        if ($denied) {
            return 403;
        }

        location / {
            echo "ip = $http_x_forwarded_for";
            echo "code = $geoip2_country_code";
            echo "name = $geoip2_country_name";
        }
    }
}
```



## Request Execution Examples

```console
$ curl -H'X-Forwarded-For: 51.68.138.153' http://127.0.0.1


403 Forbidden

403 Forbidden
Angie/1.12.1


```

```console
$ curl -H'X-Forwarded-For: 8.8.8.8' http://127.0.0.1

ip = 8.8.8.8
code = US
name = United States
```

```console
$ curl -H'X-Forwarded-For: 77.88.44.242' http://127.0.0.1

ip = 77.88.44.242
code = RU
name = Russia
```



## Additional Information

**Version:** 3.4

Detailed documentation and source code are available at:
[https://github.com/leev/ngx_http_geoip2_module](https://github.com/leev/ngx_http_geoip2_module)


# https://en.angie.software/angie/docs/configuration/modules/external-modules/headers-more.md





# Headers More

The headers-more module allows you to add, set, or remove any outgoing or incoming headers.



## Installation

To [install](https://en.angie.software//angie/docs/installation/index.md#install-packages) the module, use one of the following packages:

- Angie: `angie-module-headers-more`
- Angie PRO: `angie-pro-module-headers-more`



## Loading the Module

To use the module, it must be loaded in the `main{}` context:

```nginx
load_module modules/ngx_http_headers_more_filter_module.so;
```

In the configuration example below, directives from the echo module are also used along with the module's own directives.
Loading the echo module:

```nginx
load_module modules/ngx_http_echo_module.so;
```



## Configuration Example

```nginx
http {
    server {
        listen 80;

        root  /usr/share/angie/html;
        index index.html index.htm;

        location /clear {
            more_clear_headers 'Content-Type';
            proxy_pass http://127.0.0.1:8081;
        }

        location /settype {
            more_set_headers 'Content-Type: text/plain';
            proxy_pass http://127.0.0.1:8081;
        }

        location /changetype {
            more_set_headers -t 'text/plain text/css' 'Content-Type: text/newtype';
            proxy_pass http://127.0.0.1:8081;
        }

        location /newheader {
            more_set_headers -t 'text/plain text/css' 'New-Header: foo';
            proxy_pass http://127.0.0.1:8081;
        }

        location /404 {
            more_set_headers -s '400 404 500 503' 'Upstream-Status: $upstream_status';
            proxy_pass http://127.0.0.1:8081;
        }

        location /input {
            set $my_host 'my.host';
            more_set_input_headers 'Host: $my_host';
            more_set_input_headers -t 'text/plain' 'X-Foo: bar';

            echo "Host: $host";
            echo "X-foo: $http_x_foo";
        }
    }

    server {
        listen 8081;
        default_type text/css;

        location / {
            return 200 "OK\n";
        }

        location /404 {
            return 404 "Done\n";
        }
    }
}
```



## Additional Information

**Version:** v0.39

Detailed documentation and source code are available at:
[https://github.com/openresty/headers-more-nginx-module/](https://github.com/openresty/headers-more-nginx-module/)


# https://en.angie.software/angie/docs/configuration/modules/external-modules/http-auth-radius.md





# HTTP Auth RADIUS

This module provides HTTP authentication using the RADIUS protocol.



## Installation

To [install](https://en.angie.software//angie/docs/installation/index.md#install-packages) the module, use one of the
following packages:

- Angie: `angie-module-http-auth-radius`
- Angie PRO: `angie-pro-module-http-auth-radius`



## Loading the Module

Load the module in the `main{}` context:

```nginx
load_module modules/ngx_http_auth_radius_module.so;
```



## Configuration Example

```nginx
http {

    radius_server "radius_server1" {
        auth_timeout 5;
        resend_limit 3;
        url "127.0.0.1:1812";
        share_secret "secret";
    }

    server {
        listen 80;
        server_name localhost;

        location = / {
            root html;
            index index.html index.htm;

            # RADIUS server configuration
            # The third parameter defines the authentication method:
            # PAP CHAP MSCHAP MSCHAP2 EAPMD5

            auth_radius_server "radius_server1" "PAP";

            # Parameter values:
            # Restricted, "Close Content", off

            auth_radius "Restricted";
        }
    }
}
```



## Additional Information

**Version:** 458af16

Detailed documentation and source code are available at:
[https://github.com/ten0s/ngx_http_auth_radius_module/](https://github.com/ten0s/ngx_http_auth_radius_module/)


# https://en.angie.software/angie/docs/configuration/modules/external-modules/http_js.md





# HTTP JS

The module is used to implement handlers in njs — a subset of the JavaScript language.

In our repositories, the module is built
[dynamically](https://en.angie.software//angie/docs/installation/index.md#install-dynamicmodules)
and is available as a separate package named `angie-module-njs` or `angie-pro-module-njs`.

#### NOTE
A lightweight version of the package, named `...-njs-light`, is also
available; however, it can't be used side by side with the regular one.



## Configuration Example

```nginx
http {
    js_import http.js;

    js_set $foo     http.foo;
    js_set $summary http.summary;
    js_set $hash    http.hash;

    resolver 10.0.0.1;

    server {
        listen 8000;

        location / {
            add_header X-Foo $foo;
            js_content http.baz;
        }

        location = /summary {
            return 200 $summary;
        }

        location = /hello {
            js_content http.hello;
        }

        location = /fetch {
            js_content                   http.fetch;
            js_fetch_trusted_certificate /path/to/ISRG_Root_X1.pem;
        }

        location = /crypto {
            add_header Hash $hash;
            return     200;
        }
    }
}
```

The `http.js` file:

```javascript
function foo(r) {
    r.log("hello from foo() handler");
    return "foo";
}

function summary(r) {
    var a, s, h;

    s = "JS summary\n\n";

    s += "Method: " + r.method + "\n";
    s += "HTTP version: " + r.httpVersion + "\n";
    s += "Host: " + r.headersIn.host + "\n";
    s += "Remote Address: " + r.remoteAddress + "\n";
    s += "URI: " + r.uri + "\n";

    s += "Headers:\n";
    for (h in r.headersIn) {
        s += "  header '" + h + "' is '" + r.headersIn[h] + "'\n";
    }

    s += "Args:\n";
    for (a in r.args) {
        s += "  arg '" + a + "' is '" + r.args[a] + "'\n";
    }

    return s;
}

function baz(r) {
    r.status = 200;
    r.headersOut.foo = 1234;
    r.headersOut['Content-Type'] = "text/plain; charset=utf-8";
    r.headersOut['Content-Length'] = 15;
    r.sendHeader();
    r.send("nginx");
    r.send("java");
    r.send("script");

    r.finish();
}

function hello(r) {
    r.return(200, "Hello world!");
}

async function fetch(r) {
    let results = await Promise.all([ngx.fetch('https://example.com/'),
                                     ngx.fetch('https://example.org/')]);

    r.return(200, JSON.stringify(results, undefined, 4));
}

async function hash(r) {
    let hash = await crypto.subtle.digest('SHA-512', r.headersIn.host);
    r.setReturnValue(Buffer.from(hash).toString('hex'));
}

export default {foo, summary, baz, hello, fetch, hash};
```



## Directives





### js_body_filter

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_body_filter` function | module.function [`buffer_type=``string` | `buffer`];   |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------|
| Default                                                                                  | —                                                                                  |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | location, if in location, limit_except                                             |

Sets an njs function as a response body filter. The filter function is called for each data chunk of a response body with the following arguments:

| `r`     | the [HTTP request](https://en.angie.software//angie/docs/configuration/njs-reference.md#njs-http-request) object   |
|---------|--------------------------------------------------------------------------------------------------------------------|
| `data`  | the incoming data chunk, may be a string or Buffer depending on the buffer_type value, by default is a string.     |
| `flags` | an object with the following properties:
- `last` — a boolean value, `true` if data is the last buffer         |

The filter function can pass its own modified version of the input data chunk to the next body filter by calling [r.sendBuffer()](https://en.angie.software//angie/docs/configuration/njs-reference.md#r-sendbuffer). For example, to transform all the lowercase letters in the response body:

```javascript
function filter(r, data, flags) {
    r.sendBuffer(data.toLowerCase(), flags);
}
```

To stop filtering (following data chunks will be passed to client without calling js_body_filter), [r.done()](https://en.angie.software//angie/docs/configuration/njs-reference.md#r-done) can be used.

If the filter function changes the length of the response body, then it is required to clear out the `Content-Length` response header (if any) in [js_header_filter](#js-header-filter) to enforce chunked transfer encoding.

#### NOTE
As the js_body_filter handler returns its result immediately, it supports only synchronous operations. Thus, asynchronous operations such as [r.subrequest()](https://en.angie.software//angie/docs/configuration/njs-reference.md#r-subrequest) or [setTimeout()](https://en.angie.software//angie/docs/configuration/njs-reference.md#njs-timers) are not supported.





### js_content

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_content` function | module.function;   |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| Default                                                                                  | —                                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | location, if in location, limit_except     |

Sets an njs function as a location content handler. Module functions can be referenced.





### js_context_reuse

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_context_reuse` number;   |
|------------------------------------------------------------------------------------------|------------------------------|
| Default                                                                                  | `js_context_reuse 128;`      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location       |

Sets the maximum number of JS contexts to be reused for the QuickJS engine. Each context is used for a single request. The finished context is put into a pool of reusable contexts. If the pool is full, the context is destroyed.





### js_engine

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_engine` `njs` | `qjs`;   |
|------------------------------------------------------------------------------------------|------------------------------|
| Default                                                                                  | `js_engine njs;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location       |

Sets the JavaScript engine to be used for njs scripts. The `njs` parameter sets the njs engine, also used by default. The `qjs` parameter sets the QuickJS engine.





### js_fetch_buffer_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_fetch_buffer_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `js_fetch_buffer_size 16k;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                |

Sets the size of the buffer used for reading and writing with [Fetch API](https://en.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch).





### js_fetch_ciphers

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_fetch_ciphers` ciphers;          |
|------------------------------------------------------------------------------------------|--------------------------------------|
| Default                                                                                  | `js_fetch_ciphers HIGH:!aNULL:!MD5;` |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location               |

Specifies the enabled ciphers for HTTPS connections with [Fetch API](https://en.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch). The ciphers are specified in the format understood by the OpenSSL library.

The list of ciphers depends on the version of OpenSSL installed.
The full list can be viewed using the `openssl ciphers` command.





### js_fetch_keepalive

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_fetch_keepalive` connections;   |
|------------------------------------------------------------------------------------------|-------------------------------------|
| Default                                                                                  | `js_fetch_keepalive 0;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location              |

Activates the cache for connections to destination servers. When the value is greater than `0`, enables keepalive connections for [Fetch API](https://en.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch).

The connections parameter sets the maximum number of idle keepalive connections to destination servers that are preserved in the cache of each worker process. When this number is exceeded, the least recently used connections are closed.

Example:

```nginx
location /fetch {
    js_fetch_keepalive 32;
    js_fetch_trusted_certificate /path/to/ISRG_Root_X1.pem;
    js_content main.fetch_handler;
}
```





### js_fetch_keepalive_requests

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_fetch_keepalive_requests` number;   |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| Default                                                                                  | `js_fetch_keepalive_requests 1000;`     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                  |

Sets the maximum number of requests that can be served through one keepalive connection with [Fetch API](https://en.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch). After the maximum number of requests is made, the connection is closed.

Closing connections periodically is necessary to free per-connection memory allocations. Therefore, using too high maximum number of requests could result in excessive memory usage and is not recommended.





### js_fetch_keepalive_time

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_fetch_keepalive_time` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `js_fetch_keepalive_time 1h;`                                                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                   |

Limits the maximum time during which requests can be processed through one keepalive connection with [Fetch API](https://en.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch). After this time is reached, the connection is closed following the subsequent request processing.





### js_fetch_keepalive_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_fetch_keepalive_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `js_fetch_keepalive_timeout 60s;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                      |

Sets a timeout during which an idle keepalive connection to a destination server will stay open with [Fetch API](https://en.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch).





### js_fetch_max_response_buffer_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_fetch_max_response_buffer_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `js_fetch_max_response_buffer_size 1m;`                                                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                                             |

Sets the maximum size of the response received with [Fetch API](https://en.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch).





### js_fetch_protocols

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_fetch_protocols` [`TLSv1`] [`TLSv1.1`] [`TLSv1.2`] [`TLSv1.3`];   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|
| Default                                                                                  | `js_fetch_protocols TLSv1 TLSv1.1 TLSv1.2;`                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                |

Enables the specified protocols for HTTPS connections with [Fetch API](https://en.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch).





### js_fetch_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_fetch_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `js_fetch_timeout 60s;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                            |

Defines a timeout for reading and writing for [Fetch API](https://en.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch). The timeout is set only between two successive read/write operations, not for the whole response. If no data is transmitted within this time, the connection is closed.





### js_fetch_trusted_certificate

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_fetch_trusted_certificate` file;   |
|------------------------------------------------------------------------------------------|----------------------------------------|
| Default                                                                                  | —                                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                 |

Specifies a file with trusted CA certificates in the PEM format used to verify the HTTPS certificate with [Fetch API](https://en.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch).





### js_fetch_verify

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_fetch_verify` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-----------------------------------|
| Default                                                                                  | `js_fetch_verify on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location            |

Enables or disables verification of the HTTPS server certificate with [Fetch API](https://en.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch).





### js_fetch_verify_depth

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_fetch_verify_depth` number;   |
|------------------------------------------------------------------------------------------|-----------------------------------|
| Default                                                                                  | `js_fetch_verify_depth 100;`      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location            |

Sets the verification depth in the HTTPS certificates chain with [Fetch API](https://en.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch).





### js_header_filter

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_header_filter` function | module.function;   |
|------------------------------------------------------------------------------------------|--------------------------------------------------|
| Default                                                                                  | —                                                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | location, if in location, limit_except           |

Sets an njs function as a response header filter. The directive allows changing arbitrary header fields of a response header.

#### NOTE
As the js_header_filter handler returns its result immediately, it supports only synchronous operations. Thus, asynchronous operations such as [r.subrequest()](https://en.angie.software//angie/docs/configuration/njs-reference.md#r-subrequest) or [setTimeout()](https://en.angie.software//angie/docs/configuration/njs-reference.md#njs-timers) are not supported.





### js_import

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_import` module.js | export_name from module.js;   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------|
| Default                                                                                  | —                                                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                |

Imports a module that implements location and variable handlers in njs. The export_name is used as a namespace to access module functions. If the export_name is not specified, the module name will be used as a namespace.

```nginx
js_import http.js;
```

Here, the module name `http` is used as a namespace while accessing
exports. If the imported module exports `foo()`, `http.foo` is used
to refer to it.

Several `js_import` directives can be specified.





### js_path

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_path` path;        |
|------------------------------------------------------------------------------------------|------------------------|
| Default                                                                                  | —                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location |

Sets an additional path for njs modules.





### js_periodic

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_periodic` module.function [`interval=`\\ time] [`jitter=`\\ number] [`worker_affinity=`\\ mask];   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------|
| Default                                                                                  | —                                                                                                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | location                                                                                               |

Specifies a content handler to run at regular intervals. The handler receives a session object as its first argument, it also has access to global objects such as ngx.

The optional `interval` parameter sets the interval between two consecutive runs, by default, 5 seconds.

The optional `jitter` parameter sets the time within which the location content handler will be randomly delayed, by default, there is no delay.

By default, the `js_handler` is executed on worker process 0. The optional `worker_affinity` parameter allows specifying particular worker processes where the location content handler should be executed. Each worker process set is represented by a bitmask of allowed worker processes. The `all` mask allows the handler to be executed in all worker processes.

Example:

```nginx
example.conf:

location @periodics {
    # to be run at 1 minute intervals in worker process 0
    js_periodic main.handler interval=60s;

    # to be run at 1 minute intervals in all worker processes
    js_periodic main.handler interval=60s worker_affinity=all;

    # to be run at 1 minute intervals in worker processes 1 and 3
    js_periodic main.handler interval=60s worker_affinity=0101;

    resolver 10.0.0.1;
    js_fetch_trusted_certificate /path/to/ISRG_Root_X1.pem;
}
```

```javascript
example.js:

async function handler(s) {
    let reply = await ngx.fetch('https://example.com/');
    let body = await reply.text();

    ngx.log(ngx.INFO, body);
}
```





### js_preload_object

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_preload_object` name.json | name from file.json;   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------|
| Default                                                                                  | —                                                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                 |

Preloads an immutable object at configure time. The name is used as a name of the global variable through which the object is available in njs code. If the name is not specified, the file name will be used instead.

```nginx
js_preload_object map.json;
```

Here, the map is used as a name while accessing the preloaded object.

Several js_preload_object directives can be specified.





### js_set

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_set` $variable function | module.function [`nocache`];   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------|
| Default                                                                                  | —                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                       |

Sets an njs function for the specified variable. Module functions can be referenced.

The function is called when the variable is referenced for the first time for a given request. The exact moment depends on a [phase](https://en.angie.software//angie/docs/configuration/processing.md#stream-sessions) at which the variable is referenced. This can be used to perform some logic not related to variable evaluation. For example, if the variable is referenced only in the [log_format](https://en.angie.software//angie/docs/configuration/modules/http/http_log.md#log-format) directive, its handler will not be executed until the log phase. This handler can be used to do some cleanup right before the request is freed.

Since njs 0.8.6, if an optional `nocache` argument is specified, the handler is called every time it is referenced. Due to current limitations of the rewrite module, when a `nocache` variable is referenced by the set directive its handler should always return a fixed-length value.

#### NOTE
As the js_set handler returns its result immediately, it supports only synchronous operations. Thus, asynchronous operations such as [r.subrequest()](https://en.angie.software//angie/docs/configuration/njs-reference.md#r-subrequest) or [setTimeout()](https://en.angie.software//angie/docs/configuration/njs-reference.md#njs-timers) are not supported.





### js_shared_dict_zone

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_shared_dict_zone` `zone=`name:size [`timeout=`time] [`type=``string` | `number`] [`evict`] [`state=`file];   |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | —                                                                                                                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                                                                                                             |

Sets the name and size of the shared memory zone that keeps the key-value dictionary shared between worker processes.

| `type`    | optional parameter, allows redefining the value type to `number`;
by default, the shared dictionary uses `string` for keys and values   |
|-----------|---------------------------------------------------------------------------------------------------------------------------------------------|
| `timeout` | optional parameter, sets the time after which all shared dictionary entries are removed from the zone                                       |
| `evict`   | optional parameter, removes the oldest key-value pair when the zone storage is exhausted                                                    |
| `state`   | optional parameter, specifies a file that keeps the shared dictionary state in JSON format and makes it persistent across nginx restarts    |

Examples:

```nginx
example.conf:
    # Creates a 1MB dictionary with string values,
    # key-value pairs are removed after 60 seconds of inactivity:
    js_shared_dict_zone zone=foo:1M timeout=60s;

    # Creates a 512KB dictionary with string values,
    # oldest key-value pair is removed when the zone overflows:
    js_shared_dict_zone zone=bar:512K timeout=30s evict;

    # Creates a persistent 32KB dictionary with numeric values:
    js_shared_dict_zone zone=num:32k type=number;

    # Creates a 1MB dictionary with string values and persistent state:
    js_shared_dict_zone zone=persistent:1M state=/tmp/dict.json;
```

```javascript
example.js:
    function get(r) {
        r.return(200, ngx.shared.foo.get(r.args.key));
    }

    function set(r) {
        r.return(200, ngx.shared.foo.set(r.args.key, r.args.value));
    }

    function delete(r) {
        r.return(200, ngx.shared.bar.delete(r.args.key));
    }

    function increment(r) {
        r.return(200, ngx.shared.num.incr(r.args.key, 2));
    }
```





### js_var

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_var` $variable [value];   |
|------------------------------------------------------------------------------------------|-------------------------------|
| Default                                                                                  | —                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location        |

Declares a [writable](https://en.angie.software//angie/docs/configuration/njs-reference.md#r-variables) variable. The value can contain text, variables, and their combination. The variable is not overwritten after a redirect, unlike variables created with the set directive.



## Request Argument

Each HTTP njs handler receives one argument, a [request](https://en.angie.software//angie/docs/configuration/njs-reference.md#njs-http-request) object.


# https://en.angie.software/angie/docs/configuration/modules/external-modules/jwt.md





# JWT

The module enables validation of JSON Web Tokens (JWT) using specified keys.
It is **incompatible** with the [Auth JWT](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-jwt.md#external-auth-jwt) module.



## Installation

To [install](https://en.angie.software//angie/docs/installation/index.md#install-packages) the module, use one of the
following packages:

- Angie: `angie-module-jwt`
- Angie PRO: `angie-pro-module-jwt`



## Loading the Module

Enable the module in the `main{}` context:

```nginx
load_module modules/ngx_http_auth_jwt_module.so;
```



## Configuration Example

```nginx
http {
    server {
        auth_jwt_key "0123456789abcdef" hex;
        auth_jwt     off;

        # Authorization via the Authentication header
        location /secured-by-auth-header/ {
            auth_jwt on;
        }

        # Authorization via cookie
        location /secured-by-cookie/ {
            auth_jwt $cookie_MyCookieName;
        }

        # Key inheritance and override
        location /secured-by-auth-header-too/ {
            auth_jwt_key "another-secret";
            auth_jwt on;
        }

        # Authorization via RSA key
        location /secured-by-rsa-key/ {
            auth_jwt_key /etc/keys/rsa-public.pem file;
            auth_jwt on;
        }

        location /not-secure/ {}
    }
}
```



## Additional Information

**Version:** v3.4.4

For detailed documentation and source code, see:
[https://github.com/max-lt/nginx-jwt-module](https://github.com/max-lt/nginx-jwt-module)


# https://en.angie.software/angie/docs/configuration/modules/external-modules/keyval.md





# Keyval

The module allows the use of variables with values from "key-value" pairs,
which are stored in shared memory or in a Redis store.



## Installation

To [install](https://en.angie.software//angie/docs/installation/index.md#install-packages) the module, use one of the following packages:

- Angie: `angie-module-keyval`
- Angie PRO: `angie-pro-module-keyval`



## Loading the Module

To work with the module, it must be loaded in the `main{}` context:

```nginx
load_module modules/ngx_http_keyval_module.so;
```



## Configuration Example

```nginx
keyval_zone zone=one:32k;
keyval $arg_key $value zone=one;

server {
    listen 80;
    server_name localhost;

    location /get {
        return 200 "key '$arg_key' has value = '$value'\\n";
    }

    location /set {
        set $value $arg_value;
        return 200 "'$arg_key' key added with '$arg_value' value\\n";
    }
}
```

Adding and modifying entries in the shared memory zone 'one' is done by
assigning a value to the `$value` variable. The key value
is stored in the `$arg_key` variable. In this configuration, this is done via the
`set` directive:

```nginx
set $value $arg_value;
```



## Demonstration

Let's define some values using requests:

```console
$ curl "localhost/set/?key=one&value=TextForKeyOne"

  'one' key added with 'TextForKeyOne' value
```

```console
$ curl "localhost/set/?key=two&value=TextForKeyTwo"

  'two' key added with 'TextForKeyTwo' value
```

Let's check:

```console
$ curl "localhost/get/?key=one"

  key 'one' has value = 'TextForKeyOne'
```

```console
$ curl "localhost/get/?key=two"

  key 'two' has value = 'TextForKeyTwo'
```



## Using Redis

Let's modify the configuration to store "key-value" pairs in a Redis store:

```nginx
keyval_zone_redis zone=oneredis;
keyval $arg_key $value zone=oneredis;

server {
    listen 80;
    server_name localhost;

    location /get {
        return 200 "key '$arg_key' has value = '$value'\\n";
    }

    location /set {
        set $value $arg_value;
        return 200 "'$arg_key' key added with '$arg_value' value\\n";
    }
}
```

Let's add a "key-value" pair to the Redis store via a request:

```console
$ curl "localhost/set/?key=one&value=TextForKeyOne"

  'one' key added with 'TextForKeyOne' value
```

The same can be done using Redis itself:

```console
$ redis-cli

  127.0.0.1:6379> set oneredis:two 'text for key two'

  OK

  127.0.0.1:6379>
```

Let's check:

```console
$ redis-cli --scan

  "oneredis:one"
  "oneredis:two"
```

```console
$ curl "localhost/get/?key=one"

  key 'one' has value = 'TextForKeyOne'
```

```console
$ curl "localhost/get/?key=two"

  key 'two' has value = 'text for key two'
```



## Additional Information

**Version:** 0.5.0

A complete description of the directives and the source code is available at:
[https://github.com/kjdev/nginx-keyval](https://github.com/kjdev/nginx-keyval).


# https://en.angie.software/angie/docs/configuration/modules/external-modules/lua.md





# Lua

The Lua package integrates the Lua programming language into Angie's event-driven
processing model, allowing the server's functionality to be extended with Lua scripts.
It consists of two modules:

- `lua-nginx-module` — [https://github.com/openresty/lua-nginx-module](https://github.com/openresty/lua-nginx-module)
- `stream-lua-nginx-module` —
  [https://github.com/openresty/stream-lua-nginx-module](https://github.com/openresty/stream-lua-nginx-module)



## Installation

To [install](https://en.angie.software//angie/docs/installation/index.md#install-packages) the module, use one of the following packages:

- Angie: `angie-module-lua`;
- Angie PRO: `angie-pro-module-lua`.



## Features

Example use cases:

- aggregating and processing output from various `upstream` servers
  (proxy, drizzle, postgres, redis, memcached, etc.);
- implementing access control and security logic before passing the request
  to the backend;
- modifying response headers;
- retrieving upstream server data from external sources and dynamically selecting
  the `upstream`;
- building complete web applications inside the `content handler`;
- performing URL routing during the rewrite phase;
- implementing advanced caching for subrequests and `location` blocks.

The LuaJIT environment offers performance comparable to C, with high execution
speed and low memory usage. This makes Lua integration especially efficient in Angie.



## Loading the Module

Using the Lua module requires loading the `ndk` module beforehand.
Modules are loaded in the `main{}` context as follows:

```nginx
load_module modules/ndk_http_module.so;
load_module modules/ngx_http_lua_module.so;    # for HTTP
load_module modules/ngx_stream_lua_module.so;  # for Stream
```



## Bundled Lua Libraries

The following third-party libraries are installed along with the Lua modules:

1. [luajit2](https://github.com/openresty/luajit2)
2. [lua_chronos](https://github.com/ldrumm/chronos)
3. [lua_cjson](https://github.com/mpx/lua-cjson)
4. [lua-dumper](https://github.com/edubart/lua-dumper)
5. [lua-ffi-zlib](https://github.com/hamishforbes/lua-ffi-zlib)
6. [inspect.lua](https://github.com/kikito/inspect.lua)
7. [lua-resty-core](https://github.com/openresty/lua-resty-core)
8. [lua-resty-hmac](https://github.com/jkeys089/lua-resty-hmac)
9. [lua-resty-http](https://github.com/ledgetech/lua-resty-http)
10. [lua-resty-jwt](https://github.com/cdbattags/lua-resty-jwt)
11. [lua-resty-lrucache](https://github.com/openresty/lua-resty-lrucache)
12. [lua-resty-openidc](https://github.com/zmartzone/lua-resty-openidc)
13. [lua-resty-openssl](https://github.com/fffonion/lua-resty-openssl)
14. [lua-resty-session](https://github.com/bungle/lua-resty-session)
15. [lua-resty-string](https://github.com/openresty/lua-resty-string)



## Additional Information

**Version:** 0.10.31 / v0.0.17

Comprehensive documentation and source code are available at:

- [https://github.com/openresty/lua-nginx-module](https://github.com/openresty/lua-nginx-module)
- [https://github.com/openresty/stream-lua-nginx-module](https://github.com/openresty/stream-lua-nginx-module)


# https://en.angie.software/angie/docs/configuration/modules/external-modules/modsecurity.md





# ModSecurity

The module adds a connector for using [ModSecurity](https://modsecurity.org/) rules.



## Installation

To [install](https://en.angie.software//angie/docs/installation/index.md#install-packages) the module, use one of the following packages:

- Angie: `angie-module-modsecurity`
- Angie PRO: `angie-pro-module-modsecurity`



## Loading the Module

To work with the module, you need to load it in the `main{}` context:

```nginx
load_module modules/ngx_http_modsecurity_module.so;
```



## Configuration Example

Specify the `modsecurity` and `modsecurity_rules_file` directives
in the appropriate context, for example `server`:

> ```nginx
> server {
>     modsecurity on;
>     modsecurity_rules_file /etc/angie/modsecurity/rules.conf;
>     # ...
> }
> ```

Copy the [OWASP Core Rule Set for ModSecurity (CRS)](https://coreruleset.org/)
to the `/var/lib/angie/modsecurity/` directory:

> ```console
> $ cd /var/lib/angie/modsecurity/
> $ sudo git clone -b v4.1.0 https://github.com/coreruleset/coreruleset
> ```

In the directory with the core rules,
copy the minimally required ModSecurity configuration examples:

```console
$ sudo cp coreruleset/crs-setup.conf.example coreruleset/crs-setup.conf
$ sudo cp coreruleset/rules/REQUEST-900-EXCLUSION-RULES-BEFORE-CRS.conf.example \
      coreruleset/rules/REQUEST-900-EXCLUSION-RULES-BEFORE-CRS.conf
$ sudo cp coreruleset/rules/RESPONSE-999-EXCLUSION-RULES-AFTER-CRS.conf.example \
      coreruleset/rules/RESPONSE-999-EXCLUSION-RULES-AFTER-CRS.conf
```

Uncomment the `Include` directives below
in the `/etc/angie/modsecurity/rules.conf` file:

```apache
Include /var/lib/angie/modsecurity/coreruleset/crs-setup.conf
Include /var/lib/angie/modsecurity/coreruleset/rules/*.conf
```



## Additional Information

**Version:** v1.0.4

Detailed documentation and source code are available at:
[https://github.com/owasp-modsecurity/ModSecurity-nginx](https://github.com/owasp-modsecurity/ModSecurity-nginx).


# https://en.angie.software/angie/docs/configuration/modules/external-modules/ndk.md





# NDK

NDK is a module designed to extend core functionality in such a way that it can be used as a foundation for other Angie modules.

NDK itself adds several functions that are not visible from the user's perspective — it is simply intended to help reduce the amount of code that module developers need to write.

Among the set of modules whose packages are available in the Angie repository, NDK is used in the following modules:

- `lua`
- `set-misc`

When using them, in addition to loading the necessary module, you should also load the NDK module. NDK must be loaded before the main module.



## Installation

To [install](https://en.angie.software//angie/docs/installation/index.md#install-packages) the module, use one of the following packages:

- Angie: `angie-module-ndk`
- Angie PRO: `angie-pro-module-ndk`



## Loading the Module

```nginx
load_module modules/ndk_http_module.so;
```



## Additional Information

**Version:** v0.3.4

Detailed documentation and source code are available at the following link:
[https://github.com/vision5/ngx_devel_kit/](https://github.com/vision5/ngx_devel_kit/)


# https://en.angie.software/angie/docs/configuration/modules/external-modules/njs.md





# NJS

The module provides integration of the JavaScript programming language into
Angie's event processing model and allows extending server functionality using
JavaScript scripts. It consists of two modules:

- [HTTP JS](https://en.angie.software//angie/docs/configuration/modules/external-modules/http_js.md#http-js) — for processing HTTP traffic;
- [Stream JS](https://en.angie.software//angie/docs/configuration/modules/external-modules/stream_js.md#stream-js) — for processing TCP/UDP traffic.



## Installation

To [install](https://en.angie.software//angie/docs/installation/index.md#install-packages) the module, use one of
the following packages:

- Angie: `angie-module-njs` or `angie-module-njs-light`;
- Angie PRO: `angie-pro-module-njs` or `angie-pro-module-njs-light`.



## Features

The module extends server functionality using scripts written in njs,
a subset of JavaScript, enabling implementation of custom server-side logic
and much more:

- Complex access control and security checks before
  the request reaches the proxied server.
- Response header manipulation.
- Writing flexible asynchronous handlers and content filters.

Also available is a standalone command-line utility that can be used
independently of the server for developing and debugging njs scripts.



## Loading the Module

Loading modules in the `main{}` context:

```nginx
load_module modules/ngx_http_js_module.so;    # for HTTP
load_module modules/ngx_stream_js_module.so;  # for Stream
```



## Usage

Detailed documentation is available in the sections for individual modules:

- [HTTP JS](https://en.angie.software//angie/docs/configuration/modules/external-modules/http_js.md#http-js)
- [Stream JS](https://en.angie.software//angie/docs/configuration/modules/external-modules/stream_js.md#stream-js)



## Security

The module does not execute dynamic code, especially code received from the network.
The only way to execute such code using njs is to configure the
`js_import` directive in the server configuration. JavaScript code is loaded once
at server startup.

In the module's threat model, JavaScript code is considered a trusted source just like
the configuration file and site certificates. In practice, this means the following:

- disclosure of memory contents and other security issues caused by
  modification of JavaScript code are not considered security issues,
  but are treated as regular bugs;
- measures must be taken to protect the JavaScript code used by the module;
- if there are no `js_import` directives in the configuration file,
  the server is protected from vulnerabilities related to JavaScript.



## Command-Line Utility

The **njs** command-line utility helps develop and debug njs scripts
and is installed along with the modules. Unlike when the module runs
as part of Angie, Angie objects (`HTTP` and
`Stream`) are not available when using the utility.

Examples of using the utility:

```console
$ echo "2**3" | njs -q
8

$ njs

>> globalThis
global {
 njs: njs {
  version: '0.3.9'
 },
 global: [Circular],
 process: process {
  argv: [
   '/usr/bin/njs'
  ],
...
```



## Preloaded Objects

For each incoming request, the module creates a separate virtual machine. This
provides many benefits, such as predictable memory consumption and
request isolation. However, since all requests are isolated, if a request
handler needs to access any data, it must read it
itself. This is inefficient, especially when the data volume is large.

To solve this problem, a mechanism for preloaded shared objects was introduced.
Such objects are created as immutable and have no prototype chains: their values
cannot be changed, properties cannot be added or removed.

Here are a few examples of working with preloaded objects in njs:

- Accessing properties by name:
  ```javascript
  preloaded_object.prop_name
  preloaded_object[prop_name]
  ```
- Enumerating properties:
  ```javascript
  for (i in preloaded_object_name) {
        // ...
  }
  ```
- Applying non-modifying built-in methods using `call()`:
  ```javascript
  Array.prototype.filter.call(preloaded_object_name, ...)
  ```



## API Reference

For a complete reference of all njs objects, methods, and properties, see:

- [njs API Reference](https://en.angie.software//angie/docs/configuration/njs-reference.md#njs-reference)



## Additional Information

**Version:** 1.0.0

- Official website: [https://nginx.org/en/docs/njs/](https://nginx.org/en/docs/njs/)
- Usage examples: [https://github.com/nginx/njs-examples/](https://github.com/nginx/njs-examples/)


# https://en.angie.software/angie/docs/configuration/modules/external-modules/opentracing.md





# OpenTracing

The Opentracing module adds distributed OpenTracing request tracing to
Angie; it includes plugins for exporting data to Zipkin and DataDog.



## Installation

To [install](https://en.angie.software//angie/docs/installation/index.md#install-packages) the module, use one of the following packages:

- Angie: `angie-module-opentracing`
- Angie PRO: `angie-pro-module-opentracing`



## Loading the Module

To work with the module, it must be loaded in the `main{}` context:

```nginx
load_module modules/ngx_http_opentracing_module.so;
```



## Configuration Example

```nginx
http {
    opentracing on;

    opentracing_load_tracer /usr/local/lib/libdd_opentracing_plugin.so /etc/datadog-config.json;

    upstream backend {
        server app-service:9001;
    }

    server {
        error_log /var/log/angie/debug.log debug;
        listen 8080;
        server_name localhost;

        location = / {
            opentracing_trace_locations off;
            proxy_pass http://backend;
            opentracing_propagate_context;
            opentracing_tag "resource.name" "/";
        }
    }
}
```



## Additional Information

**Version:** 0.48.0

Various configuration options can be found at:
[https://github.com/opentracing-contrib/nginx-opentracing/tree/master/example](https://github.com/opentracing-contrib/nginx-opentracing/tree/master/example)

Detailed documentation and source code are available at:
[https://github.com/opentracing-contrib/nginx-opentracing](https://github.com/opentracing-contrib/nginx-opentracing)


# https://en.angie.software/angie/docs/configuration/modules/external-modules/otel.md





# OpenTelemetry

The OTel module provides support for OpenTelemetry distributed tracing.
The module supports W3C context propagation and the OTLP/gRPC export protocol.



## Installation

To [install](https://en.angie.software//angie/docs/installation/index.md#install-packages) the module, use one of the following packages:

- Angie: `angie-module-otel`
- Angie PRO: `angie-pro-module-otel`



## Loading the Module

To use the module, it must be loaded in the `main{}` context:

```nginx
load_module modules/ngx_otel_module.so;
```



## Configuration Example

```nginx
http {
    otel_exporter {
        endpoint localhost:4317;
    }

    server {
        listen 80;

        location / {
            otel_trace         on;
            otel_trace_context inject;

            proxy_pass http://backend;
        }
    }
}
```



## Additional Information

**Version:** v0.1.2

Detailed documentation and source code are available at:
[https://github.com/nginxinc/nginx-otel](https://github.com/nginxinc/nginx-otel)


# https://en.angie.software/angie/docs/configuration/modules/external-modules/postgres.md





# PostgreSQL

The Postgres module provides direct support for PostgreSQL databases.



## Installation

To [install](https://en.angie.software//angie/docs/installation/index.md#install-packages) the module, use one of the following packages:

- Angie: `angie-module-postgres`
- Angie PRO: `angie-pro-module-postgres`



## Loading the Module

Load the module in the `main{}` context:

```nginx
load_module modules/ngx_postgres_module.so;
```



## Configuration Example

```nginx
http {
    upstream database {
        postgres_server 127.0.0.1 dbname=ang_test
                         user=ang_test password=ang_test;
    }

    server {
        listen 80;
        postgres_output text;

        location /create {
            postgres_pass database;
            postgres_query "CREATE TABLE cats (id integer, name text)";
        }

        location /insert {
            postgres_pass database;
            postgres_query "INSERT INTO cats (id, name) VALUES ($arg_id, '$arg_name')";
        }

        location /select {
            postgres_pass database;
            postgres_query "SELECT name FROM cats WHERE id=$arg_id";
        }
    }
}
```



## Additional Information

**Version:** 1.0rc7

Detailed documentation and source code are available at:
[https://github.com/FRiCKLE/ngx_postgres](https://github.com/FRiCKLE/ngx_postgres)


# https://en.angie.software/angie/docs/configuration/modules/external-modules/redis2.md





# Redis2

The `redis2` module provides the ability to interact with a Redis
2.x server. It implements the full unified Redis 2.0 protocol, including support
for Redis pipelining.



## Installation

To [install](https://en.angie.software//angie/docs/installation/index.md#install-packages) the module, use one of the following packages:

- Angie: `angie-module-redis2`
- Angie PRO: `angie-pro-module-redis2`



## Loading the Module

To work with the module, it must be loaded in the `main{}` context.
The example below also uses directives from the [Set Misc](https://en.angie.software//angie/docs/configuration/modules/external-modules/set-misc.md#external-set-misc) module:

```nginx
load_module modules/ndk_http_module.so;
load_module modules/ngx_http_set_misc_module.so;
load_module modules/ngx_http_redis2_module.so;
```



## Configuration Example

```nginx
upstream redis_upstream {
    server 127.0.0.1:6379;
}

server {
    listen       80;
    server_name  localhost;

    # Set a key value
    location /foo {
        set $value 'first';
        redis2_query set one $value;
        redis2_pass redis_upstream;
    }

    # Get a value by key
    location /bar {
        redis2_query get one;
        redis2_pass redis_upstream;
    }

    # Set a key value from query parameters
    location /set {
        set_unescape_uri $key $arg_key;
        set_unescape_uri $val $arg_val;
        redis2_query set $key $val;
        redis2_pass 127.0.0.1:6379;
    }

    # Get a value by key from query parameters
    location /get {
        set_unescape_uri $key $arg_key;
        redis2_query get $key;
        redis2_pass 127.0.0.1:6379;
    }

    # Execute multiple pipelined commands
    location /pipeline {
        set $value 'first';
        redis2_query set one $value;
        redis2_query get one;
        redis2_query set one 'first first';
        redis2_query get one;
        redis2_pass 127.0.0.1:6379;
    }

    # Execute an arbitrary command passed in a query parameter
    location /cmd {
        set_unescape_uri $cmd $arg_command;
        redis2_raw_query "$cmd\r\n";
        redis2_pass 127.0.0.1:6379;
    }
}
```

#### WARNING
Important! Unlike the `proxy_pass` directive in Angie, using variables in the parameter of the `redis2_pass` directive is not allowed.



## Request Execution Demonstration

Examples of working with the module.

```console
$ curl localhost/foo
+OK

$ curl localhost/bar
$5
first
```

Here `$5` is the length of the value (5 bytes), and `first` is the value itself.

```console
$ curl 'localhost/set/?key=two&val=second%20value'
+OK

$ curl 'localhost/get/?key=two'
$12
second value

$ curl 'localhost/get/?key=three'
$-1
```

The value `$-1` indicates that the key `three` does not exist.

```console
$ curl localhost/pipeline
+OK
$5
first
+OK
$11
first first
```

Executing arbitrary Redis commands:

```console
$ curl 'localhost/cmd/?command=set%20three%20"third%20value"'
+OK

$ curl 'localhost/cmd/?command=get%20three'
$11
third value
```



## Additional Information

**Version:** v0.15

Detailed documentation and source code are available at:
[https://github.com/openresty/redis2-nginx-module](https://github.com/openresty/redis2-nginx-module).


# https://en.angie.software/angie/docs/configuration/modules/external-modules/rtmp.md





# RTMP

The RTMP module provides live streaming capabilities in HLS and MPEG-DASH formats for those who want to use a simplified solution based on the HTTP protocol. The stream is published in MPEG-TS format over HTTP.



## Installation

To [install](https://en.angie.software//angie/docs/installation/index.md#install-packages) the module, use one of the following packages:

- Angie: `angie-module-rtmp`;
- Angie PRO: `angie-pro-module-rtmp`.



## Loading the Module

Load the module in the `main{}` context:

```nginx
load_module modules/ngx_rtmp_module.so;
```



## Configuration Example

```nginx
http {
    server {
        listen 443 ssl;
        server_name example.com;

        ssl_certificate /var/ssl/example.com.pem;
        ssl_certificate_key /var/ssl/example.com.private;

        location /keys {
            root /tmp;
        }
    }

    server {
        listen 80;
        server_name example.com;

        location /hls {
            root /tmp;
        }
    }
}

rtmp {
    server {
        listen 1935;

        hls on;
        hls_path /tmp/hls;
        hls_keys on;
        hls_key_path /tmp/keys;
        hls_key_url https://example.com/keys/;
        hls_fragments_per_key 2;
    }
}
```



## Additional Information

**Version:** v1.2.2

Detailed documentation and source code are available at:
[https://github.com/arut/nginx-rtmp-module](https://github.com/arut/nginx-rtmp-module)


# https://en.angie.software/angie/docs/configuration/modules/external-modules/set-misc.md





# Set Misc

The `set-misc` module extends the standard functionality of the Rewrite module by adding support for URI escaping and unescaping, JSON quote handling, as well as various encoding and decoding methods (HEX, MD5, SHA1, Base32, Base64) and other operations.

It allows solving the following tasks:

- **URI Processing**: escaping and unescaping URIs.
- **Encoding and Decoding**: support for HEX, MD5, SHA1, Base32, Base64.
- **Additional Functions**: working with JSON quotes and other utility features.



## Installation

To [install](https://en.angie.software//angie/docs/installation/index.md#install-packages) the module, use one of the following packages:

- Angie: `angie-module-set-misc`
- Angie PRO: `angie-pro-module-set-misc`



## Loading the Module

To work with the module, it must be loaded in the context of `main{}`. The example below also uses directives from the [Echo](https://en.angie.software//angie/docs/configuration/modules/external-modules/echo.md#external-echo) module:

```nginx
load_module modules/ndk_http_module.so;
load_module modules/ngx_http_set_misc_module.so;
load_module modules/ngx_http_echo_module.so;
```



## Configuration Example

```nginx
server {
    listen 80;
    server_name localhost;

    location /ifempty {
        set $a $arg_a;
        set_if_empty $a 56;

        echo "arg_a = '$arg_a'";
        echo "a = '$a'";
    }

    location /unescape {
        set_unescape_uri $a $arg_a;
        set_escape_uri $b $a;

        echo "arg_a = '$arg_a'";
        echo "a = '$a'";
        echo "b = '$b'";
    }

    location /base32 {
        set_encode_base32 $a $arg_a;
        set_decode_base32 $b $a;

        echo "arg_a = '$arg_a'";
        echo "a = '$a'";
        echo "b = '$b'";
    }

    location /hex {
        set_encode_hex $a $arg_a;
        set_decode_hex $b $a;

        echo "arg_a = '$arg_a'";
        echo "a = '$a'";
        echo "b = '$b'";
    }
}
```



## Demonstration

```console
$ curl localhost/ifempty/?a=100

  arg_a = '100'
  a = '100'

$ curl localhost/ifempty

  arg_a = ''
  a = '56'

$ curl localhost/unescape/?a=Hello%20world!

  arg_a = 'Hello%20world!'
  a = 'Hello world!'
  b = 'Hello%20world!'

$ curl localhost/base32/?a=abcde

  arg_a = 'abcde'
  a = 'c5h66p35'
  b = 'abcde'

$ curl localhost/hex/?a=abcde

  arg_a = 'abcde'
  a = '6162636465'
  b = 'abcde'
```



## Additional Information

**Version:** v0.33

The full description of directives and source code is available at:
[https://github.com/openresty/set-misc-nginx-module](https://github.com/openresty/set-misc-nginx-module).


# https://en.angie.software/angie/docs/configuration/modules/external-modules/stream_js.md





# Stream JS

The module is used to implement handlers in njs — a subset of the JavaScript language.

In our repositories, the module is built [dynamically](https://en.angie.software//angie/docs/installation/index.md#install-dynamicmodules) and is available as a separate package named
`angie-module-njs` or `angie-pro-module-njs`.

#### NOTE
A lightweight version of the package, named `...-njs-light`, is also
available; however, it can't be used side by side with the regular one.



## Configuration Example

```nginx
stream {
    js_import stream.js;

    js_set $bar stream.bar;
    js_set $req_line stream.req_line;

    server {
        listen 12345;

        js_preread stream.preread;
        return     $req_line;
    }

    server {
        listen 12346;

        js_access  stream.access;
        proxy_pass 127.0.0.1:8000;
        js_filter  stream.header_inject;
    }
}

http {
    server {
        listen 8000;
        location / {
            return 200 $http_foo\n;
        }
    }
}
```

The `stream.js` file:

```javascript
var line = '';

function bar(s) {
    var v = s.variables;
    s.log("hello from bar() handler!");
    return "bar-var" + v.remote_port + "; pid=" + v.pid;
}

function preread(s) {
    s.on('upload', function (data, flags) {
        var n = data.indexOf('\n');
        if (n != -1) {
            line = data.substr(0, n);
            s.done();
        }
    });
}

function req_line(s) {
    return line;
}

// Read HTTP request line.
// Collect bytes in 'req' until
// request line is read.
// Inject HTTP header into a client's request

var my_header =  'Foo: foo';
function header_inject(s) {
    var req = '';
    s.on('upload', function(data, flags) {
        req += data;
        var n = req.search('\n');
        if (n != -1) {
            var rest = req.substr(n + 1);
            req = req.substr(0, n + 1);
            s.send(req + my_header + '\r\n' + rest, flags);
            s.off('upload');
        }
    });
}

function access(s) {
    if (s.remoteAddress.match('^192.*')) {
        s.deny();
        return;
    }

    s.allow();
}

export default {bar, preread, req_line, header_inject, access};
```



## Directives





### js_access

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_access` function | module.function;   |
|------------------------------------------------------------------------------------------|-------------------------------------------|
| Default                                                                                  | —                                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                            |

Sets an njs function which will be called at the [access phase](https://en.angie.software//angie/docs/configuration/processing.md#stream-sessions). Module functions can be referenced.

The function is called once at the moment when the stream session reaches the [access phase](https://en.angie.software//angie/docs/configuration/processing.md#stream-sessions) for the first time. The function is called with the following arguments:

| `s`   | the [stream session](https://en.angie.software//angie/docs/configuration/njs-reference.md#njs-stream-session) object   |
|-------|------------------------------------------------------------------------------------------------------------------------|

At this phase, it is possible to perform initialization or register a callback with the [s.on()](https://en.angie.software//angie/docs/configuration/njs-reference.md#s-on) method for each incoming data chunk until one of the following methods are called: [s.done()](https://en.angie.software//angie/docs/configuration/njs-reference.md#njs-s-done), [s.decline()](https://en.angie.software//angie/docs/configuration/njs-reference.md#njs-s-decline), [s.allow()](https://en.angie.software//angie/docs/configuration/njs-reference.md#njs-s-allow). As soon as one of these methods is called, the stream session processing switches to the [next phase](https://en.angie.software//angie/docs/configuration/processing.md#stream-sessions) and all current [s.on()](https://en.angie.software//angie/docs/configuration/njs-reference.md#s-on) callbacks are dropped.





### js_context_reuse

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_context_reuse` number;   |
|------------------------------------------------------------------------------------------|------------------------------|
| Default                                                                                  | `js_context_reuse 128;`      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server               |

Sets the maximum number of JS contexts to be reused for the QuickJS engine. Each context is used for a single stream session. The finished context is put into a pool of reusable contexts. If the pool is full, the context is destroyed.





### js_engine

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_engine` `njs` | `qjs`;   |
|------------------------------------------------------------------------------------------|------------------------------|
| Default                                                                                  | `js_engine njs;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server               |

Sets the JavaScript engine to be used for njs scripts. The `njs` parameter sets the njs engine, also used by default. The `qjs` parameter sets the QuickJS engine.





### js_fetch_buffer_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_fetch_buffer_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `js_fetch_buffer_size 16k;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                                                                                                        |

Sets the size of the buffer used for reading and writing with [Fetch API](https://en.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch).





### js_fetch_ciphers

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_fetch_ciphers` ciphers;          |
|------------------------------------------------------------------------------------------|--------------------------------------|
| Default                                                                                  | `js_fetch_ciphers HIGH:!aNULL:!MD5;` |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                       |

Specifies the enabled ciphers for HTTPS connections with [Fetch API](https://en.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch). The ciphers are specified in the format understood by the OpenSSL library.

The list of ciphers depends on the version of OpenSSL installed.
The full list can be viewed using the `openssl ciphers` command.





### js_fetch_keepalive

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_fetch_keepalive` connections;   |
|------------------------------------------------------------------------------------------|-------------------------------------|
| Default                                                                                  | `js_fetch_keepalive 0;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                      |

Activates the cache for connections to destination servers. When the value is greater than `0`, enables keepalive connections for [Fetch API](https://en.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch).

The connections parameter sets the maximum number of idle keepalive connections to destination servers that are preserved in the cache of each worker process. When this number is exceeded, the least recently used connections are closed.

Example:

```nginx
server {
    listen 12345;
    js_fetch_keepalive 32;
    js_fetch_trusted_certificate /path/to/ISRG_Root_X1.pem;
    js_preread main.fetch_handler;
}
```





### js_fetch_keepalive_requests

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_fetch_keepalive_requests` number;   |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| Default                                                                                  | `js_fetch_keepalive_requests 1000;`     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                          |

Sets the maximum number of requests that can be served through one keepalive connection with [Fetch API](https://en.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch). After the maximum number of requests is made, the connection is closed.

Closing connections periodically is necessary to free per-connection memory allocations. Therefore, using too high maximum number of requests could result in excessive memory usage and is not recommended.





### js_fetch_keepalive_time

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_fetch_keepalive_time` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `js_fetch_keepalive_time 1h;`                                                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                                                                                                           |

Limits the maximum time during which requests can be processed through one keepalive connection with [Fetch API](https://en.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch). After this time is reached, the connection is closed following the subsequent request processing.





### js_fetch_keepalive_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_fetch_keepalive_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `js_fetch_keepalive_timeout 60s;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                                                                                                              |

Sets a timeout during which an idle keepalive connection to a destination server will stay open with [Fetch API](https://en.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch).





### js_fetch_max_response_buffer_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_fetch_max_response_buffer_size` [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `js_fetch_max_response_buffer_size 1m;`                                                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                                                                                                                     |

Sets the maximum size of the response received with [Fetch API](https://en.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch).





### js_fetch_protocols

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_fetch_protocols` [`TLSv1`] [`TLSv1.1`] [`TLSv1.2`] [`TLSv1.3`];   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|
| Default                                                                                  | `js_fetch_protocols TLSv1 TLSv1.1 TLSv1.2;`                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                                                        |

Enables the specified protocols for HTTPS connections with [Fetch API](https://en.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch).





### js_fetch_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_fetch_timeout` [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units);   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `js_fetch_timeout 60s;`                                                                                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                                                                                                    |

Defines a timeout for reading and writing for [Fetch API](https://en.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch). The timeout is set only between two successive read/write operations, not for the whole response. If no data is transmitted within this time, the connection is closed.





### js_fetch_trusted_certificate

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_fetch_trusted_certificate` file;   |
|------------------------------------------------------------------------------------------|----------------------------------------|
| Default                                                                                  | —                                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                         |

Specifies a file with trusted CA certificates in the PEM format used to verify the HTTPS certificate with [Fetch API](https://en.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch).





### js_fetch_verify

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_fetch_verify` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-----------------------------------|
| Default                                                                                  | `js_fetch_verify on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                    |

Enables or disables verification of the HTTPS server certificate with [Fetch API](https://en.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch).





### js_fetch_verify_depth

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_fetch_verify_depth` number;   |
|------------------------------------------------------------------------------------------|-----------------------------------|
| Default                                                                                  | `js_fetch_verify_depth 100;`      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                    |

Sets the verification depth in the HTTPS server certificates chain with [Fetch API](https://en.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch).





### js_filter

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_filter` function | module.function;   |
|------------------------------------------------------------------------------------------|-------------------------------------------|
| Default                                                                                  | —                                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                            |

Sets a data filter. Module functions can be referenced.

The filter function is called once at the moment when the stream session reaches the [content phase](https://en.angie.software//angie/docs/configuration/processing.md#stream-sessions). The filter function is called with the following arguments:

| `s`   | the [stream session](https://en.angie.software//angie/docs/configuration/njs-reference.md#njs-stream-session) object   |
|-------|------------------------------------------------------------------------------------------------------------------------|

At this phase, it is possible to perform initialization or register a callback with the [s.on()](https://en.angie.software//angie/docs/configuration/njs-reference.md#s-on) method for each incoming data chunk. The [s.off()](https://en.angie.software//angie/docs/configuration/njs-reference.md#s-off) method may be used to unregister a callback and stop filtering.

#### NOTE
As the js_filter handler returns its result immediately, it supports only synchronous operations. Thus, asynchronous operations such as [ngx.fetch()](https://en.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch) or [setTimeout()](https://en.angie.software//angie/docs/configuration/njs-reference.md#njs-timers) are not supported.





### js_import

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_import` module.js | export_name from module.js;   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------|
| Default                                                                                  | —                                                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                                        |

Imports a module that implements location and variable handlers in njs. The export_name is used as a namespace to access module functions. If the export_name is not specified, the module name will be used as a namespace.

```nginx
js_import stream.js;
```

Here, the module name stream is used as a namespace when accessing exports. If the imported module exports foo(), then stream.foo is used to access it.

Several js_import directives can be specified.





### js_path

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_path` path;   |
|------------------------------------------------------------------------------------------|-------------------|
| Default                                                                                  | —                 |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server    |

Sets an additional path for njs modules.





### js_periodic

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_periodic` module.function [`interval=`\\ time] [`jitter=`\\ number] [`worker_affinity=`\\ mask];   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------|
| Default                                                                                  | —                                                                                                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | server                                                                                                 |

Specifies a content handler to run at regular intervals. The handler receives a session object as its first argument, it also has access to global objects such as `ngx`.

The optional `interval` parameter sets the interval between two consecutive runs, by default, 5 seconds.

The optional `jitter` parameter sets the time within which the location content handler will be randomly delayed, by default, there is no delay.

By default, the `js_handler` is executed on worker process 0. The optional `worker_affinity` parameter allows specifying particular worker processes where the location content handler should be executed. Each worker process set is represented by a bitmask of allowed worker processes. The `all` mask allows the handler to be executed in all worker processes.

Example:

```nginx
example.conf:

location @periodics {
    # to be run at 1 minute intervals in worker process 0
    js_periodic main.handler interval=60s;

    # to be run at 1 minute intervals in all worker processes
    js_periodic main.handler interval=60s worker_affinity=all;

    # to be run at 1 minute intervals in worker processes 1 and 3
    js_periodic main.handler interval=60s worker_affinity=0101;

    resolver 10.0.0.1;
    js_fetch_trusted_certificate /path/to/ISRG_Root_X1.pem;
}
```

```javascript
example.js:

async function handler(s) {
    let reply = await ngx.fetch('https://example.com/');
    let body = await reply.text();

    ngx.log(ngx.INFO, body);
}
```





### js_preload_object

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_preload_object` name.json | name from file.json;   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------|
| Default                                                                                  | —                                                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                                         |

Preloads an immutable object at configure time. The name is used as a name of the global variable though which the object is available in njs code. If the name is not specified, the file name will be used instead.

```nginx
js_preload_object map.json;
```

Here, the map is used as a name while accessing the preloaded object.

Several js_preload_object directives can be specified.





### js_preread

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_preread` function | module.function;   |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| Default                                                                                  | —                                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                             |

Sets an njs function which will be called at the [preread phase](https://en.angie.software//angie/docs/configuration/processing.md#stream-sessions). Module functions can be referenced.

The function is called once at the moment when the stream session reaches the [preread phase](https://en.angie.software//angie/docs/configuration/processing.md#stream-sessions) for the first time. The function is called with the following arguments:

| `s`   | the [stream session](https://en.angie.software//angie/docs/configuration/njs-reference.md#njs-stream-session) object   |
|-------|------------------------------------------------------------------------------------------------------------------------|

At this phase, it is possible to perform initialization or register a callback with the [s.on()](https://en.angie.software//angie/docs/configuration/njs-reference.md#s-on) method for each incoming data chunk until one of the following methods are called: [s.done()](https://en.angie.software//angie/docs/configuration/njs-reference.md#njs-s-done), [s.decline()](https://en.angie.software//angie/docs/configuration/njs-reference.md#njs-s-decline), [s.allow()](https://en.angie.software//angie/docs/configuration/njs-reference.md#njs-s-allow). When one of these methods is called, the stream session switches to the [next phase](https://en.angie.software//angie/docs/configuration/processing.md#stream-sessions) and all current [s.on()](https://en.angie.software//angie/docs/configuration/njs-reference.md#s-on) callbacks are dropped.

#### NOTE
As the js_preread handler returns its result immediately, it supports only synchronous operations. Thus, asynchronous operations such as [ngx.fetch()](https://en.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch) or [setTimeout()](https://en.angie.software//angie/docs/configuration/njs-reference.md#njs-timers) are not supported. Nevertheless, asynchronous operations are supported in [s.on()](https://en.angie.software//angie/docs/configuration/njs-reference.md#s-on) callbacks in the [preread phase](https://en.angie.software//angie/docs/configuration/processing.md#stream-sessions).





### js_set

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_set` $variable function | module.function [`nocache`];   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------|
| Default                                                                                  | —                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                                               |

Sets an njs function for the specified variable. Module functions can be referenced.

The function is called when the variable is referenced for the first time for a given request. The exact moment depends on a [phase](https://en.angie.software//angie/docs/configuration/processing.md#stream-sessions) at which the variable is referenced. This can be used to perform some logic not related to variable evaluation. For example, if the variable is referenced only in the [log_format](https://en.angie.software//angie/docs/configuration/modules/stream/stream_log.md#s-log-format) directive, its handler will not be executed until the log phase. This handler can be used to do some cleanup right before the request is freed.

Since njs 0.8.6, when optional argument `nocache` is provided the handler is called every time it is referenced. Due to current limitations of the rewrite module, when a `nocache` variable is referenced by the set directive its handler should always return a fixed-length value.

#### NOTE
As the js_set handler returns its result immediately, it supports only synchronous operations. Thus, asynchronous operations such as [ngx.fetch()](https://en.angie.software//angie/docs/configuration/njs-reference.md#ngx-fetch) or [setTimeout()](https://en.angie.software//angie/docs/configuration/njs-reference.md#njs-timers) are not supported.





### js_shared_dict_zone

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_shared_dict_zone` `zone=`name:size [`timeout=`time] [`type=``string` | `number`] [`evict`] [`state=`file];   |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | —                                                                                                                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream                                                                                                           |

Sets the name and size of the shared memory zone that keeps the key-value dictionary shared between worker processes.

| `type`    | optional parameter, allows redefining the value type to `number`, by default the shared dictionary uses a `string` as a key and a value   |
|-----------|-------------------------------------------------------------------------------------------------------------------------------------------|
| `timeout` | optional parameter, sets the time after which all shared dictionary entries are removed from the zone                                     |
| `evict`   | optional parameter, removes the oldest key-value pair when the zone storage is exhausted                                                  |
| `state`   | optional parameter, specifies a file that keeps the shared dictionary state in JSON format and makes it persistent across nginx restarts  |

Examples:

```nginx
example.conf:
    # Creates a 1Mb dictionary with string values,
    # removes key-value pairs after 60 seconds of inactivity:
    js_shared_dict_zone zone=foo:1M timeout=60s;

    # Creates a 512Kb dictionary with string values,
    # forcibly removes oldest key-value pairs when the zone is exhausted:
    js_shared_dict_zone zone=bar:512K timeout=30s evict;

    # Creates a 32Kb permanent dictionary with number values:
    js_shared_dict_zone zone=num:32k type=number;

    # Creates a 1Mb dictionary with string values and persistent state:
    js_shared_dict_zone zone=persistent:1M state=/tmp/dict.json;
```

```javascript
example.js:
    function get(r) {
        r.return(200, ngx.shared.foo.get(r.args.key));
    }

    function set(r) {
        r.return(200, ngx.shared.foo.set(r.args.key, r.args.value));
    }

    function delete(r) {
        r.return(200, ngx.shared.bar.delete(r.args.key));
    }

    function increment(r) {
        r.return(200, ngx.shared.num.incr(r.args.key, 2));
    }
```





### js_var

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `js_var` $variable [value];   |
|------------------------------------------------------------------------------------------|-------------------------------|
| Default                                                                                  | —                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                |

Declares a [writable](https://en.angie.software//angie/docs/configuration/njs-reference.md#s-variables) variable. The value can contain text, variables, and their combination.



## Session Object Properties

Each stream njs handler receives one argument, a [stream session](https://en.angie.software//angie/docs/configuration/njs-reference.md#njs-stream-session) object.


# https://en.angie.software/angie/docs/configuration/modules/external-modules/subs.md





# Subs

The Subs module allows for the replacement of strings in the body of HTTP responses (both fixed and using regular expressions). All occurrences found in the response body are replaced.



## Installation

To [install](https://en.angie.software//angie/docs/installation/index.md#install-packages) the module, use one of the following packages:

- Angie: `angie-module-subs`;
- Angie PRO: `angie-pro-module-subs`.



## Loading the Module

To include the module in the context of `main{}`:

```nginx
load_module modules/ngx_http_subs_filter_module.so;
```



## Configuration Example

```nginx
http {
    server {
        listen 80;

        location / {
            subs_filter_types text/html text/css text/xml;
            subs_filter st(\d*).example.com $1.example.com ir;
            subs_filter a.example.com s.example.com;
            subs_filter http://$host https://$host;
        }
    }
}
```



## Additional Information

**Version:** e12e965

Detailed documentation and source code are available at:
[https://github.com/yaoweibin/ngx_http_substitutions_filter_module](https://github.com/yaoweibin/ngx_http_substitutions_filter_module)


# https://en.angie.software/angie/docs/configuration/modules/external-modules/testcookie.md





# TestCookie

This module provides bot protection using a cookie-based challenge-response mechanism.



## Installation

To [install](https://en.angie.software//angie/docs/installation/index.md#install-packages) the module, use one of the following packages:

- Angie: `angie-module-testcookie`
- Angie PRO: `angie-pro-module-testcookie`



## Loading the Module

Enable the module in the `main{}` context:

```nginx
load_module modules/ngx_http_testcookie_access_module.so;
```



## Configuration Example

```none
http {
    testcookie off;
    testcookie_name BPC;
    testcookie_secret keepmesecret;
    testcookie_session $remote_addr;
    testcookie_arg ckattempt;
    testcookie_max_attempts 3;
    testcookie_p3p 'CP="CUR ADM OUR NOR STA NID", policyref="/w3c/p3p.xml"';
    testcookie_fallback http://google.com/cookies.html?backurl=http://$host$request_uri;

    testcookie_whitelist {
        8.8.8.8/32;
    }

    testcookie_redirect_via_refresh on;
    testcookie_refresh_encrypt_cookie on;
    testcookie_refresh_encrypt_cookie_key deadbeefdeadbeefdeadbeefdeadbeef;
    testcookie_refresh_encrypt_cookie_iv deadbeefdeadbeefdeadbeefdeadbeef;
    testcookie_refresh_template 'setting cookie...';

    server {
        listen 80;
        server_name test.com;

        location = /aes.min.js {
            gzip on;
            gzip_min_length 1000;
            gzip_types text/plain;
            root /var/www/public_html;
        }

        location = /w3c/p3p.xml {
            root /var/www/public_html;
        }

        location = /.well-known/acme-challenge/ {
            root /var/www/public_html;
        }

        location / {
            testcookie on;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_pass http://127.0.0.1:80;
        }
    }
}
```



## Additional Information

**Version:** 7d263d4

Detailed documentation and source code are available at:
[https://github.com/kyprizel/testcookie-nginx-module/](https://github.com/kyprizel/testcookie-nginx-module/)


# https://en.angie.software/angie/docs/configuration/modules/external-modules/unbrotli.md





# UnBrotli

The `unbrotli` module is designed for decompressing responses from the
backend that use Brotli compression (`Content-Encoding: br`) for clients
that do not support this compression method. This is particularly useful in
cases where storing data in compressed form on the backend saves space.



## Installation

To [install](https://en.angie.software//angie/docs/installation/index.md#install-packages) the module, use one of the following packages:

- Angie: `angie-module-unbrotli`
- Angie PRO: `angie-pro-module-unbrotli`



## Directives

The module provides the following directives:

- `unbrotli` – similar to [gunzip](https://en.angie.software//angie/docs/configuration/modules/http/http_gunzip.md#id1)
- `unbrotli_buffers` – similar to [gunzip_buffers](https://en.angie.software//angie/docs/configuration/modules/http/http_gunzip.md#gunzip-buffers)



## Loading the Module

To use the module, it must be loaded in the `main{}` context:

```nginx
load_module modules/ngx_http_unbrotli_filter_module.so;
```



## Configuration Example

```nginx
server {
    listen 80 default_server;
    location / {
        root  /usr/share/angie/html;
        index index.html;
    }

    location /storage {
        unbrotli on;
        proxy_pass http://127.0.0.1:8080;
    }
}

# Backend
server {
    listen 8080;
    location /storage {
        root   /usr/share/angie;
        rewrite ^(.*)$ $1.br break;  # Return the compressed file with .br suffix
        add_header Content-Encoding br; # Indicate Brotli compression in the response header
    }
}
```



## Demonstration

Let's place the compressed test file `war-and-peace.txt.br`:

```console
$ ls -l /usr/share/angie/storage/
total 2292
-rw-r--r-- 1 root root 1115616 Feb 27 16:10 war-and-peace.txt.br
```

If the client supports Brotli, it will receive the compressed file without decompression:

```console
$ curl -s -H 'Accept-Encoding: br' -o tmp/war-and-peace.txt localhost/storage/war-and-peace.txt

$ ls -l tmp/
total 1092
-rw-r--r-- 1 asv asv 1115616 Feb 27 16:36 war-and-peace.txt
```

If the client does not support Brotli, the `unbrotli` module will decompress the file on the server before sending:

```console
$ curl -s -o tmp/war-and-peace.txt localhost/storage/war-and-peace.txt

$ ls -l tmp/
total 3284
-rw-r--r-- 1 asv asv 3359405 Feb 27 16:39 war-and-peace.txt
```

The file was decompressed by the server before being sent to the client.



## Additional Information

**Version:** 60bed63

Detailed documentation and source code are available at:
[https://github.com/clyfish/ngx_unbrotli](https://github.com/clyfish/ngx_unbrotli).


# https://en.angie.software/angie/docs/configuration/modules/external-modules/upload.md





# Upload

The `upload` module provides file upload functionality with support for
`multipart/form-data` encoding, as defined by RFC 1867. It also includes
support for resumable uploads using the `POST` method.



## Installation

To [install](https://en.angie.software//angie/docs/installation/index.md#install-packages) the module, use one of the following packages:

- Angie: `angie-module-upload`;
- Angie PRO: `angie-pro-module-upload`.



## Loading the Module

To use the module, it must be loaded in the `main{}` context:

```nginx
load_module modules/ngx_http_upload_module.so;
```



## Additional Information

**Version:** 2.3.0

Full documentation and source code are available at:
[https://github.com/fdintino/nginx-upload-module](https://github.com/fdintino/nginx-upload-module)


# https://en.angie.software/angie/docs/configuration/modules/external-modules/vod.md





# VOD

The module allows repackaging MP4 files for streaming via HLS, HDS, MSS, and DASH.



## Installation

To [install](https://en.angie.software//angie/docs/installation/index.md#install-packages) the module, use one of the following packages:

- Angie: `angie-module-vod`
- Angie PRO: `angie-pro-module-vod`



## Operating Modes

- Local: serves locally available files (local disk or NFS mounted).
- Remote: serves files available via HTTP using range requests.
- Mapped: serves files according to a specification encoded in JSON format (JSON can be obtained from a remote server or read from a local file).



## Supported Codecs

- Video Codecs: H264, H265 (DASH/HLS), AV1 (DASH/HLS), VP8 (DASH), VP9 (DASH).
- Audio Codecs: AAC, MP3 (HLS/HDS/MSS), AC-3 (DASH/HLS), E-AC-3 (DASH/HLS), VORBIS (DASH), OPUS (DASH), FLAC (HLS), DTS (HLS).



## Loading the Module

Load the module in the `main{}` context:

```nginx
load_module modules/ngx_http_vod_module.so;
```



## Configuration Example

```nginx
location ~ ^/cenchls/p/\d+/(sp/\d+/)?serveFlavor/entryId/([^/]+)/(.*) {
    vod hls;
    vod_hls_encryption_method sample-aes-cenc;
    vod_hls_encryption_key_format "urn:uuid:edef8ba9-79d6-4ace-a3c8-27dcd51d21ed";
    vod_hls_encryption_key_format_versions "1";

    vod_drm_enabled on;
    vod_drm_request_uri "/udrm/system/ovp/$vod_suburi";

    vod_last_modified_types *;
    add_header Access-Control-Allow-Headers '*';
    add_header Access-Control-Expose-Headers 'Server,range,Content-Length,Content-Range';
    add_header Access-Control-Allow-Methods 'GET, HEAD, OPTIONS';
    add_header Access-Control-Allow-Origin '*';
    expires 100d;
}
```



## Additional Information

**Version:** 1.9.0

Detailed documentation and source code are available at:
[https://github.com/kaltura/nginx-vod-module](https://github.com/kaltura/nginx-vod-module).


# https://en.angie.software/angie/docs/configuration/modules/external-modules/vts.md





# VTS

This is a set of modules for traffic tracking and real-time activity monitoring. It provides access to information about the status of virtual hosts, upstreams, caches, and also includes ready-made HTML templates to visualize statistics.



## Installation

To [install](https://en.angie.software//angie/docs/installation/index.md#install-packages) the module, use one of the following packages:

- Angie: `angie-module-vts`
- Angie PRO: `angie-pro-module-vts`



## Loading Modules

Loading the modules in the `main{}` context:

```nginx
load_module modules/ngx_http_stream_server_traffic_status_module.so;
load_module modules/ngx_http_vhost_traffic_status_module.so;
load_module modules/ngx_stream_server_traffic_status_module.so;
```



## Preparing for Demonstration

HTML page templates are installed in the `/usr/share/angie-module-vts/` directory:

- `/usr/share/angie-module-vts/status.compress.html`
- `/usr/share/angie-module-vts/status.template.html`
- `/usr/share/angie-module-vts/stream/status.compress.html`
- `/usr/share/angie-module-vts/stream/status.template.html`

To work with the configuration example below, you need to:

1. Copy `/usr/share/angie-module-vts/status.template.html` to
   `/usr/share/angie-module-vts/status.html`:
   ```console
   $ cp /usr/share/angie-module-vts/status.template.html \
      /usr/share/angie-module-vts/status.html
   ```
2. In the `/usr/share/angie-module-vts/status.html` file, find the line:
   ```html
   var vtsStatusURI = "{{uri}}/format/json", vtsUpdateInterval = 1000;
   ```

   and replace ` *{uri*}` with `/status`.



## Configuration Example

```nginx
http {
    # ...
    vhost_traffic_status_zone;

    server {
        listen 80;
        server_name localhost;

        root  /usr/share/angie/html;
        index index.html index.htm;

        location = /status.html {
            root  /usr/share/angie-module-vts;
        }

        location /status {
            vhost_traffic_status_display;
            vhost_traffic_status_display_format html;
        }
    }
}
```



## Additional Information

**Version:** v0.2.5 / v0.1.1 / v0.1.1

Detailed documentation and source code are available at:
[https://github.com/vozlt/nginx-module-vts](https://github.com/vozlt/nginx-module-vts).


# https://en.angie.software/angie/docs/configuration/modules/external-modules/zip.md





# ZIP

The `zip` module enables dynamic generation of ZIP archives. It supports
including files retrieved from proxied servers, along with several modern ZIP
format features:

- large file support;
- UTC timestamps;
- UTF-8 encoded filenames.

These capabilities allow clients to resume large archive downloads using
`Range` and `If-Range` headers, provided the server has prior
knowledge of the files' CRC-32 checksums.



## Installation

To [install](https://en.angie.software//angie/docs/installation/index.md#install-packages) the module, use one of the following packages:

- Angie: `angie-module-zip`;
- Angie PRO: `angie-pro-module-zip`.



## Loading the Module

To use the module, it must be loaded in the `main{}` context:

```nginx
load_module modules/ngx_http_zip_module.so;
```



## Additional Information

**Version:** 1.3.0

Full documentation and source code are available at:
[https://github.com/evanmiller/mod_zip](https://github.com/evanmiller/mod_zip)


# https://en.angie.software/angie/docs/configuration/modules/external-modules/zstd.md





# Zstd

The module adds support for Zstandard compression of responses, both dynamic (on-the-fly) and static (precompressed files). Compared to gzip, zstd offers higher compression and decompression speeds at comparable or better compression ratios.

The module consists of two components:

- **http_zstd_filter** — for compressing responses dynamically;
- **http_zstd_static** — for serving precompressed files.



## Installation

To [install](https://en.angie.software//angie/docs/installation/index.md#install-packages) the module, use one of the following packages:

- Angie: `angie-module-zstd`
- Angie PRO: `angie-pro-module-zstd`



## Module Loading

Enable the modules in the `main{}` context:

```nginx
load_module modules/ngx_http_zstd_filter_module.so;
load_module modules/ngx_http_zstd_static_module.so;
```



## Example Configuration

```nginx
server {
    listen 80 default_server;

    zstd_types text/plain text/css;
    zstd_min_length 256;         # Minimum response length for compression
    zstd_comp_level 3;           # Compression level (1 to 22)

    # Dynamic file compression
    location / {
        zstd on;
        root /usr/share/angie/html;
    }

    # Dynamic compression of backend responses
    location /bk/ {
        zstd on;
        proxy_pass http://127.0.0.1:8081/;
    }

    # Using precompressed .zst files
    location /static/ {
        zstd_static on;
        root /usr/share/angie;
    }
}

server {
    listen 8081;
    location / {
        root /usr/share/angie/html;
        index index.html;
    }
}
```



## How It Works

You can combine dynamic (`zstd on`) and static (`zstd_static on`) compression. In this case, the server will first look for a precompressed `.zst` file. If it doesn't exist, it will compress the response dynamically.

Compression is only performed when the `Accept-Encoding` header includes `zstd`, for example:

```none
Accept-Encoding: gzip, zstd
```

If compression is applied or a precompressed file is found, the following response header is added:

```none
Content-Encoding: zstd
```



## More Information

**Version:** f4ba115

Full documentation and source code are available at:
[https://github.com/tokers/zstd-nginx-module](https://github.com/tokers/zstd-nginx-module)


# https://en.angie.software/angie/docs/configuration/varindex.md



# Built-in Variables

| [HTTP Modules](https://en.angie.software//angie/docs/configuration/modules/index.md#modules-http)                                                           | [Stream Modules](https://en.angie.software//angie/docs/configuration/modules/index.md#modules-stream)                                                                                                                                        |
|-------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [$acme_cert_key_](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-cert-key-name)                                 | [$acme_cert_key_](https://en.angie.software//angie/docs/configuration/modules/stream/stream_acme.md#v-s-acme-cert-key-name)                                                                                                            |
| [$acme_cert_](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-cert-name)                                         | [$acme_cert_](https://en.angie.software//angie/docs/configuration/modules/stream/stream_acme.md#v-s-acme-cert-name)                                                                                                                    |
| [$acme_hook_challenge](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-hook-challenge)                                 |                                                                                                                                                                                                                                              |
| [$acme_hook_client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-hook-client)                                       |                                                                                                                                                                                                                                              |
| [$acme_hook_domain](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-hook-domain)                                       |                                                                                                                                                                                                                                              |
| [$acme_hook_keyauth](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-hook-keyauth)                                     |                                                                                                                                                                                                                                              |
| [$acme_hook_name](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-hook-name)                                           |                                                                                                                                                                                                                                              |
| [$acme_hook_token](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-hook-token)                                         |                                                                                                                                                                                                                                              |
| [$ancient_browser](https://en.angie.software//angie/docs/configuration/modules/http/http_browser.md#v-ancient-browser)                                      |                                                                                                                                                                                                                                              |
| [$angie_version](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-angie-version)                                                 | [$angie_version](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#v-s-angie-version)                                                                                                                              |
| [$arg_](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-arg)                                                              |                                                                                                                                                                                                                                              |
| [$args](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-args)                                                                   |                                                                                                                                                                                                                                              |
| [$binary_remote_addr](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-binary-remote-addr)                                       | [$binary_remote_addr](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#v-s-binary-remote-addr)                                                                                                                    |
| [$body_bytes_sent](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-body-bytes-sent)                                             |                                                                                                                                                                                                                                              |
|                                                                                                                                                             | [$bytes_received](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#v-s-bytes-received)                                                                                                                            |
| [$bytes_sent](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-bytes-sent)                                                       | [$bytes_sent](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#v-s-bytes-sent)                                                                                                                                    |
| [$connection](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-connection)                                                       | [$connection](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#v-s-connection)                                                                                                                                    |
| [$connection_requests](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-connection-requests)                                     |                                                                                                                                                                                                                                              |
| [$connection_time](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-connection-time)                                             |                                                                                                                                                                                                                                              |
| [$connections_active](https://en.angie.software//angie/docs/configuration/modules/http/http_stub_status.md#v-connections-active)                            |                                                                                                                                                                                                                                              |
| [$connections_reading](https://en.angie.software//angie/docs/configuration/modules/http/http_stub_status.md#v-connections-reading)                          |                                                                                                                                                                                                                                              |
| [$connections_writing](https://en.angie.software//angie/docs/configuration/modules/http/http_stub_status.md#v-connections-writing)                          |                                                                                                                                                                                                                                              |
| [$connections_waiting](https://en.angie.software//angie/docs/configuration/modules/http/http_stub_status.md#v-connections-waiting)                          |                                                                                                                                                                                                                                              |
| [$content_length](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-content-length)                                               |                                                                                                                                                                                                                                              |
| [$content_type](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-content-type)                                                   |                                                                                                                                                                                                                                              |
| [$cookie_](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-cookie)                                                        |                                                                                                                                                                                                                                              |
| [$date_local](https://en.angie.software//angie/docs/configuration/modules/http/http_ssi.md#v-date-local)                                                    |                                                                                                                                                                                                                                              |
| [$date_gmt](https://en.angie.software//angie/docs/configuration/modules/http/http_ssi.md#v-date-gmt)                                                        |                                                                                                                                                                                                                                              |
| [$document_root](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-document-root)                                                 |                                                                                                                                                                                                                                              |
| [$document_uri](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-document-uri)                                                   |                                                                                                                                                                                                                                              |
| [$fastcgi_script_name](https://en.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#v-fastcgi-script-name)                              |                                                                                                                                                                                                                                              |
| [$fastcgi_path_info](https://en.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#v-fastcgi-path-info)                                  |                                                                                                                                                                                                                                              |
| [$gzip_ratio](https://en.angie.software//angie/docs/configuration/modules/http/http_gzip.md#v-gzip-ratio)                                                   |                                                                                                                                                                                                                                              |
| [$host](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-host)                                                                   |                                                                                                                                                                                                                                              |
| [$hostname](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-hostname)                                                           | [$hostname](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#v-s-hostname)                                                                                                                                        |
| [$http2](https://en.angie.software//angie/docs/configuration/modules/http/http_v2.md#v-http2)                                                               |                                                                                                                                                                                                                                              |
| [$http3](https://en.angie.software//angie/docs/configuration/modules/http/http_v3.md#v-http3)                                                               |                                                                                                                                                                                                                                              |
| [$http_](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-http)                                                            |                                                                                                                                                                                                                                              |
| [$https](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-https)                                                                 |                                                                                                                                                                                                                                              |
| [$invalid_referer](https://en.angie.software//angie/docs/configuration/modules/http/http_referer.md#v-invalid-referer)                                      |                                                                                                                                                                                                                                              |
| [$is_args](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-is-args)                                                             |                                                                                                                                                                                                                                              |
| [$is_request_port](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-is-request-port)                                             |                                                                                                                                                                                                                                              |
| [$limit_conn_status](https://en.angie.software//angie/docs/configuration/modules/http/http_limit_conn.md#v-limit-conn-status)                               | [$limit_conn_status](https://en.angie.software//angie/docs/configuration/modules/stream/stream_limit_conn.md#v-s-limit-conn-status)                                                                                                          |
| [$limit_rate](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-limit-rate)                                                       |                                                                                                                                                                                                                                              |
| [$limit_req_status](https://en.angie.software//angie/docs/configuration/modules/http/http_limit_req.md#v-limit-req-status)                                  |                                                                                                                                                                                                                                              |
| [$memcached_key](https://en.angie.software//angie/docs/configuration/modules/http/http_memcached.md#v-memcached-key)                                        |                                                                                                                                                                                                                                              |
| [$metric_](https://en.angie.software//angie/docs/configuration/modules/http/http_metric.md#v-metric-zone)                                             | [$metric_](https://en.angie.software//angie/docs/configuration/modules/stream/stream_metric.md#v-s-metric-zone)                                                                                                                        |
| [$metric__key and $metric__value](https://en.angie.software//angie/docs/configuration/modules/http/http_metric.md#v-metric-zone-key)            | [$metric__key and $metric__value](https://en.angie.software//angie/docs/configuration/modules/stream/stream_metric.md#v-s-metric-zone-key)                                                                                       |
| [$metric__key and $metric__value](https://en.angie.software//angie/docs/configuration/modules/http/http_metric.md#v-metric-zone-value)          | [$metric__key and $metric__value](https://en.angie.software//angie/docs/configuration/modules/stream/stream_metric.md#v-s-metric-zone-value)                                                                                     |
| [$metric__value_](https://en.angie.software//angie/docs/configuration/modules/http/http_metric.md#v-metric-zone-value-metric)                 | [$metric__value_](https://en.angie.software//angie/docs/configuration/modules/stream/stream_metric.md#v-s-metric-zone-value-metric)                                                                                            |
| [$modern_browser](https://en.angie.software//angie/docs/configuration/modules/http/http_browser.md#v-modern-browser)                                        |                                                                                                                                                                                                                                              |
|                                                                                                                                                             | [$mqtt_preread_clientid](https://en.angie.software//angie/docs/configuration/modules/stream/stream_mqtt_preread.md#v-mqtt-preread-clientid)                                                                                                  |
|                                                                                                                                                             | [$mqtt_preread_username](https://en.angie.software//angie/docs/configuration/modules/stream/stream_mqtt_preread.md#v-mqtt-preread-username)                                                                                                  |
| [$msec](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-msec)                                                                   | [$msec](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#v-s-msec)                                                                                                                                                |
| [$msie](https://en.angie.software//angie/docs/configuration/modules/http/http_browser.md#v-msie)                                                            |                                                                                                                                                                                                                                              |
| [Protocol](https://en.angie.software//angie/docs/configuration/modules/mail/mail_auth_http.md#v-m-protocol)                                                 |                                                                                                                                                                                                                                              |
| [$nginx_version](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-nginx-version)                                                 | [$nginx_version](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#v-s-nginx-version)                                                                                                                              |
| [$p8s_value](https://en.angie.software//angie/docs/configuration/modules/http/http_prometheus.md#v-p8s-value)                                               |                                                                                                                                                                                                                                              |
| [$pid](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-pid)                                                                     | [$pid](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#v-s-pid)                                                                                                                                                  |
| [$pipe](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-pipe)                                                                   |                                                                                                                                                                                                                                              |
| [$proxy_add_x_forwarded_for](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#v-proxy-add-x-forwarded-for)                    |                                                                                                                                                                                                                                              |
| [$proxy_host](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#v-proxy-host)                                                  |                                                                                                                                                                                                                                              |
| [$proxy_port](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#v-proxy-port)                                                  |                                                                                                                                                                                                                                              |
|                                                                                                                                                             | [$protocol](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#v-s-protocol)                                                                                                                                        |
| [$proxy_protocol_addr](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-proxy-protocol-addr)                                     | [$proxy_protocol_addr](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#v-s-proxy-protocol-addr)                                                                                                                  |
| [$proxy_protocol_port](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-proxy-protocol-port)                                     | [$proxy_protocol_port](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#v-s-proxy-protocol-port)                                                                                                                  |
| [$proxy_protocol_server_addr](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-proxy-protocol-server-addr)                       | [$proxy_protocol_server_addr](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#v-s-proxy-protocol-server-addr)                                                                                                    |
| [$proxy_protocol_server_port](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-proxy-protocol-server-port)                       | [$proxy_protocol_server_port](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#v-s-proxy-protocol-server-port)                                                                                                    |
| [$proxy_protocol_tlv_](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-proxy-protocol-tlv)                                | [$proxy_protocol_tlv_](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#v-s-proxy-protocol-tlv)                                                                                                             |
| [$query_string](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-query-string)                                                   |                                                                                                                                                                                                                                              |
| [$quic_connection](https://en.angie.software//angie/docs/configuration/modules/http/http_v3.md#v-quic-connection)                                           |                                                                                                                                                                                                                                              |
|                                                                                                                                                             | [$rdp_cookie](https://en.angie.software//angie/docs/configuration/modules/stream/stream_rdp_preread.md#v-rdp-cookie),
[$rdp_cookie_](https://en.angie.software//angie/docs/configuration/modules/stream/stream_rdp_preread.md#id3) |
| [$realip_remote_addr](https://en.angie.software//angie/docs/configuration/modules/http/http_realip.md#v-realip-remote-addr)                                 | [$realip_remote_addr](https://en.angie.software//angie/docs/configuration/modules/stream/stream_realip.md#v-s-realip-remote-addr)                                                                                                            |
| [$realip_remote_port](https://en.angie.software//angie/docs/configuration/modules/http/http_realip.md#v-realip-remote-port)                                 | [$realip_remote_port](https://en.angie.software//angie/docs/configuration/modules/stream/stream_realip.md#v-s-realip-remote-port)                                                                                                            |
| [$realpath_root](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-realpath-root)                                                 |                                                                                                                                                                                                                                              |
| [$remote_addr](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-remote-addr)                                                     | [$remote_addr](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#v-s-remote-addr)                                                                                                                                  |
| [$remote_port](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-remote-port)                                                     | [$remote_port](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#v-s-remote-port)                                                                                                                                  |
| [$remote_user](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-remote-user)                                                     |                                                                                                                                                                                                                                              |
| [$request](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-request)                                                             |                                                                                                                                                                                                                                              |
| [$request_body](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-request-body)                                                   |                                                                                                                                                                                                                                              |
| [$request_body_file](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-request-body-file)                                         |                                                                                                                                                                                                                                              |
| [$request_completion](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-request-completion)                                       |                                                                                                                                                                                                                                              |
| [$request_filename](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-request-filename)                                           |                                                                                                                                                                                                                                              |
| [$request_id](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-request-id)                                                       |                                                                                                                                                                                                                                              |
| [$request_length](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-request-length)                                               |                                                                                                                                                                                                                                              |
| [$request_method](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-request-method)                                               |                                                                                                                                                                                                                                              |
| [$request_port](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-request-port)                                                   |                                                                                                                                                                                                                                              |
| [$request_time](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-request-time)                                                   |                                                                                                                                                                                                                                              |
| [$request_uri](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-request-uri)                                                     |                                                                                                                                                                                                                                              |
| [$scheme](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-scheme)                                                               |                                                                                                                                                                                                                                              |
| [$secure_link](https://en.angie.software//angie/docs/configuration/modules/http/http_secure_link.md#v-secure-link)                                          |                                                                                                                                                                                                                                              |
| [$secure_link_expires](https://en.angie.software//angie/docs/configuration/modules/http/http_secure_link.md#v-secure-link-expires)                          |                                                                                                                                                                                                                                              |
| [$sent_http_](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-sent-http)                                                  |                                                                                                                                                                                                                                              |
| [$sent_body](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-sent-body)                                                         |                                                                                                                                                                                                                                              |
| [$sent_trailer_](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-sent-trailer)                                            |                                                                                                                                                                                                                                              |
| [$server_addr](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-server-addr)                                                     | [$server_addr](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#v-s-server-addr)                                                                                                                                  |
| [$server_name](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-server-name)                                                     |                                                                                                                                                                                                                                              |
| [$server_port](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-server-port)                                                     | [$server_port](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#v-s-server-port)                                                                                                                                  |
| [$server_protocol](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-server-protocol)                                             |                                                                                                                                                                                                                                              |
|                                                                                                                                                             | [$session_time](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#v-s-session-time)                                                                                                                                |
| [$slice_range](https://en.angie.software//angie/docs/configuration/modules/http/http_slice.md#v-slice-range)                                                |                                                                                                                                                                                                                                              |
| [$ssl_alpn_protocol](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-alpn-protocol)                                      | [$ssl_alpn_protocol](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-alpn-protocol)                                                                                                                 |
| [$ssl_cipher](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-cipher)                                                    | [$ssl_cipher](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-cipher)                                                                                                                               |
| [$ssl_ciphers](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-ciphers)                                                  | [$ssl_ciphers](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-ciphers)                                                                                                                             |
| [$ssl_client_escaped_cert](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-client-escaped-cert)                          |                                                                                                                                                                                                                                              |
|                                                                                                                                                             | [$ssl_client_cert](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-client-cert)                                                                                                                     |
| [$ssl_client_fingerprint](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-client-fingerprint)                            | [$ssl_client_fingerprint](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-client-fingerprint)                                                                                                       |
| [$ssl_client_i_dn](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-client-i-dn)                                          | [$ssl_client_i_dn](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-client-i-dn)                                                                                                                     |
| [$ssl_client_i_dn_legacy](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-client-i-dn-legacy)                            |                                                                                                                                                                                                                                              |
| [$ssl_client_raw_cert](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-client-raw-cert)                                  | [$ssl_client_raw_cert](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-client-raw-cert)                                                                                                             |
| [$ssl_client_s_dn](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-client-s-dn)                                          | [$ssl_client_s_dn](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-client-s-dn)                                                                                                                     |
| [$ssl_client_s_dn_legacy](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-client-s-dn-legacy)                            |                                                                                                                                                                                                                                              |
| [$ssl_client_serial](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-client-serial)                                      | [$ssl_client_serial](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-client-serial)                                                                                                                 |
| [$ssl_client_sigalg](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-client-sigalg)                                      | [$ssl_client_sigalg](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-client-sigalg)                                                                                                                 |
| [$ssl_client_v_end](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-client-v-end)                                        | [$ssl_client_v_end](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-client-v-end)                                                                                                                   |
| [$ssl_client_v_remain](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-client-v-remain)                                  | [$ssl_client_v_remain](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-client-v-remain)                                                                                                             |
| [$ssl_client_v_start](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-client-v-start)                                    | [$ssl_client_v_start](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-client-v-start)                                                                                                               |
| [$ssl_client_verify](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-client-verify)                                      | [$ssl_client_verify](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-client-verify)                                                                                                                 |
| [$ssl_curve](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-curve)                                                      | [$ssl_curve](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-curve)                                                                                                                                 |
| [$ssl_curves](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-curves)                                                    | [$ssl_curves](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-curves)                                                                                                                               |
| [$ssl_early_data](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-early-data)                                            | [$ssl_early_data](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-early-data)                                                                                                                       |
| [$ssl_encrypted_hello](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-encrypted-hello)                                  | [$ssl_encrypted_hello](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-encrypted-hello)                                                                                                             |
|                                                                                                                                                             | [$ssl_preread_alpn_protocols](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl_preread.md#v-ssl-preread-alpn-protocols)                                                                                         |
|                                                                                                                                                             | [$ssl_preread_protocol](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl_preread.md#v-ssl-preread-protocol)                                                                                                     |
|                                                                                                                                                             | [$ssl_preread_server_name](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl_preread.md#v-ssl-preread-server-name)                                                                                               |
| [$ssl_protocol](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-protocol)                                                | [$ssl_protocol](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-protocol)                                                                                                                           |
| [$ssl_server_name](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-server-name)                                          | [$ssl_server_name](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-server-name)                                                                                                                     |
| [$ssl_server_cert_type](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-server-cert-type)                                | [$ssl_server_cert_type](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-server-cert-type)                                                                                                           |
| [$ssl_session_id](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-session-id)                                            | [$ssl_session_id](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-session-id)                                                                                                                       |
| [$ssl_session_reused](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-session-reused)                                    | [$ssl_session_reused](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-session-reused)                                                                                                               |
| [$ssl_sigalg](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-sigalg)                                                    | [$ssl_sigalg](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-sigalg)                                                                                                                               |
| [$ssl_sigalgs](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-sigalgs)                                                  | [$ssl_sigalgs](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-sigalgs)                                                                                                                             |
| [$status](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-status)                                                               | [$status](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#v-s-status)                                                                                                                                            |
| [$sticky_sessid](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-sticky-sessid)                                         | [$sticky_sessid](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#v-s-sticky-sessid)                                                                                                                    |
| [$sticky_sid](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-sticky-sid)                                               | [$sticky_sid](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#v-s-sticky-sid)                                                                                                                          |
| [$time_iso8601](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-time-iso8601)                                                   | [$time_iso8601](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#v-s-time-iso8601)                                                                                                                                |
| [$time_local](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-time-local)                                                       | [$time_local](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#v-s-time-local)                                                                                                                                    |
| [$tcpinfo_rtt, $tcpinfo_rttvar, $tcpinfo_snd_cwnd, $tcpinfo_rcv_space](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-tcpinfo) |                                                                                                                                                                                                                                              |
| [$uid_got](https://en.angie.software//angie/docs/configuration/modules/http/http_userid.md#v-uid-got)                                                       |                                                                                                                                                                                                                                              |
| [$uid_reset](https://en.angie.software//angie/docs/configuration/modules/http/http_userid.md#v-uid-reset)                                                   |                                                                                                                                                                                                                                              |
| [$uid_set](https://en.angie.software//angie/docs/configuration/modules/http/http_userid.md#v-uid-set)                                                       |                                                                                                                                                                                                                                              |
| [$upstream_addr](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-addr)                                         | [$upstream_addr](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#v-s-upstream-addr)                                                                                                                    |
| [$upstream_current_addr (PRO)](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-current-addr)                   | [$upstream_current_addr (PRO)](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#v-s-upstream-current-addr)                                                                                              |
| [$upstream_bytes_received](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-bytes-received)                     | [$upstream_bytes_received](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#v-s-upstream-bytes-received)                                                                                                |
| [$upstream_bytes_sent](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-bytes-sent)                             | [$upstream_bytes_sent](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#v-s-upstream-bytes-sent)                                                                                                        |
| [$upstream_cache_status](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-cache-status)                         |                                                                                                                                                                                                                                              |
| [$upstream_cache_key](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-cache-key)                               |                                                                                                                                                                                                                                              |
| [$upstream_connect_time](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-connect-time)                         | [$upstream_connect_time](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#v-s-upstream-connect-time)                                                                                                    |
| [$upstream_cookie_](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-cookie)                              |                                                                                                                                                                                                                                              |
|                                                                                                                                                             | [$upstream_first_byte_time](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#v-s-upstream-first-byte-time)                                                                                              |
| [$upstream_header_time](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-header-time)                           |                                                                                                                                                                                                                                              |
| [$upstream_http_](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-http)                                  |                                                                                                                                                                                                                                              |
| [$upstream_request_method](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-request-method)                     |                                                                                                                                                                                                                                              |
| [$upstream_probe (PRO)](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#v-upstream-probe)                           | [$upstream_probe (PRO)](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#v-s-upstream-probe)                                                                                                      |
| [$upstream_probe_body (PRO)](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#v-upstream-probe-body)                 |                                                                                                                                                                                                                                              |
|                                                                                                                                                             | [$upstream_probe_response (PRO)](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#v-s-upstream-probe-response)                                                                                    |
| [$upstream_response_length](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-response-length)                   |                                                                                                                                                                                                                                              |
| [$upstream_response_time](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-response-time)                       |                                                                                                                                                                                                                                              |
|                                                                                                                                                             | [$upstream_session_time](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#v-s-upstream-session-time)                                                                                                    |
| [$upstream_status](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-status)                                     |                                                                                                                                                                                                                                              |
| [$upstream_sticky_status](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-sticky-status)                       | [$upstream_sticky_status](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#v-s-upstream-sticky-status)                                                                                                  |
| [$upstream_transport](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-transport)                               |                                                                                                                                                                                                                                              |
| [$upstream_trailer_](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-trailer)                            |                                                                                                                                                                                                                                              |
| [$upstream_queue_time](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-queue-time)                             |                                                                                                                                                                                                                                              |
| [$uri](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-uri)                                                                     |                                                                                                                                                                                                                                              |


# https://en.angie.software/angie/docs/configuration/njs-reference.md





# njs API Reference

The [NJS](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs) module provides objects, methods, and properties for extending Angie functionality.

This reference contains only NJS-specific properties, methods, and modules not compliant with ECMAScript. Definitions of NJS properties and methods compliant with ECMAScript can be found in the [ECMAScript specification](http://www.ecma-international.org/ecma-262/).



## Angie Objects



### HTTP Request

- `r.args{}`
- `r.done()`
- `r.error()`
- `r.finish()`
- `r.headersIn{}`
- `r.headersOut{}`
- `r.httpVersion`
- `r.internal`
- `r.internalRedirect()`
- `r.log()`
- `r.method`
- `r.parent`
- `r.remoteAddress`
- `r.requestBody`
- `r.requestBuffer`
- `r.requestText`
- `r.rawHeadersIn[]`
- `r.rawHeadersOut[]`
- `r.responseBody`
- `r.responseBuffer`
- `r.responseText`
- `r.return()`
- `r.send()`
- `r.sendBuffer()`
- `r.sendHeader()`
- `r.setReturnValue()`
- `r.status`
- `r.subrequest()`
- `r.uri`
- `r.rawVariables{}`
- `r.variables{}`
- `r.warn()`

The HTTP request object is available only in the [HTTP JS](https://en.angie.software//angie/docs/configuration/modules/external-modules/http_js.md#http-js) module. Before 0.8.5, all string properties of the object were byte strings.



`r.args{}`

> Request arguments object, read-only.

> The query string is returned as an object. Since 0.7.6, duplicate keys are returned as an array, keys are case-sensitive, both keys and values are percent-decoded.

> For example, the query string

> ```text
> a=1&b=%32&A=3&b=4&B=two%20words
> ```

> is converted to `r.args` as:

> ```javascript
> {a: "1", b: ["2", "4"], A: "3", B: "two words"}
> ```

> More advanced parsing scenarios can be achieved with the [Query String](#njs-querystring) module and the `$args` variable, for example:

> ```javascript
> import qs from 'querystring';

> function args(r) {
>     return qs.parse(r.variables.args);
> }
> ```

> The arguments object is evaluated at the first access to `r.args`. If only a single argument is needed, for example `foo`, Angie variables can be used:

> ```javascript
> r.variables.arg_foo
> ```

> Here, the Angie variables object returns the first value for a given key, case-insensitive, without percent-decoding.

> To convert `r.args` back to a string, the Query String `stringify` method can be used.



`r.done()`
: After calling this function, the next data chunks will be passed to the client without calling `js_body_filter` (0.5.2). May be called only from the `js_body_filter` function.



`r.error(string)`
: Writes a `string` to the error log on the `error` level of logging.
  

  #### NOTE
  As Angie has a hardcoded maximum line length limit, only the first 2048 bytes of the string can be logged.



`r.finish()`
: Finishes sending a response to the client.



`r.headersIn{}`
: Incoming headers object, read-only.
  

  The `Foo` request header can be accessed with the syntax: `headersIn.foo` or `headersIn['Foo']`.
  

  The `Authorization`, `Content-Length`, `Content-Range`, `Content-Type`, `ETag`, `Expect`, `From`, `Host`, `If-Match`, `If-Modified-Since`, `If-None-Match`, `If-Range`, `If-Unmodified-Since`, `Max-Forwards`, `Proxy-Authorization`, `Referer`, `Transfer-Encoding`, and `User-Agent` request headers can have only one field value (0.4.1). Duplicate field values in `Cookie` headers are separated by semicolon (`;`). Duplicate field values in all other request headers are separated by commas.



`r.headersOut{}`
: Outgoing headers object for the main request, writable.
  

  If `r.headersOut{}` is the response object of a subrequest, it represents response headers. In this case, field values in `Accept-Ranges`, `Connection`, `Content-Disposition`, `Content-Encoding`, `Content-Length`, `Content-Range`, `Date`, `Keep-Alive`, `Server`, `Transfer-Encoding`, `X-Accel-*` response headers may be omitted.
  

  The `Foo` response header can be accessed with the syntax: `headersOut.foo` or `headersOut['Foo']`.
  

  Outgoing headers should be set before a response header is sent to a client; otherwise, the header update will be ignored. This means that `r.headersOut{}` is effectively writable in:
  

  - the `js_content` handler before `r.sendHeader()` or `r.return()` are called
  - the `js_header_filter` handler
  

  Field values of multi-value response headers (0.4.0) can be set with the syntax:
  

  ```javascript
  r.headersOut['Foo'] = ['a', 'b']
  ```
  

  where the output will be:
  

  ```text
  Foo: a
  Foo: b
  ```
  

  All previous field values of the `Foo` response header will be deleted.
  

  For standard response headers that accept only a single field value such as `Content-Type`, only the last element of the array will take effect. Field values of the `Set-Cookie` response header are always returned as an array. Duplicate field values in `Age`, `Content-Encoding`, `Content-Length`, `Content-Type`, `ETag`, `Expires`, `Last-Modified`, `Location`, `Retry-After` response headers are ignored. Duplicate field values in all other response headers are separated by commas.



`r.httpVersion`
: HTTP version, read-only.



`r.internal`
: Boolean value, `true` for internal locations.



`r.internalRedirect(uri)`
: Performs an internal redirect to the specified `uri`. If the URI starts with the `@` prefix, it is considered a named location. In a new location, all request processing is repeated starting from `NGX_HTTP_SERVER_REWRITE_PHASE` for ordinary locations and from `NGX_HTTP_REWRITE_PHASE` for named locations. As a result, a redirect to a named location does not check the `client_max_body_size` limit. Redirected requests become internal and can access internal locations. The actual redirect happens after the handler execution is completed.
  

  #### NOTE
  After redirect, a new NJS VM is started in the target location, and the VM in the original location is stopped. Values of Angie variables are kept and can be used to pass information to the target location. Since 0.5.3, a variable declared with the `js_var` directive for HTTP or Stream can be used.
  

  #### NOTE
  Since 0.7.4, the method accepts escaped URIs.



`r.log(string)`
: Writes a `string` to the error log on the `info` level of logging.
  

  #### NOTE
  As Angie has a hardcoded maximum line length limit, only the first 2048 bytes of the string can be logged.



`r.method`
: HTTP method, read-only.



`r.parent`
: References the parent request object.



`r.remoteAddress`
: Client address, read-only.



`r.requestBody`
: The property was made obsolete in 0.5.0 and was removed in 0.8.0. The `r.requestBuffer` or `r.requestText` property should be used instead.



`r.requestBuffer`
: Client request body if it has not been written to a temporary file (since 0.5.0). To ensure that the client request body is in memory, its size should be limited by `client_max_body_size`, and a sufficient buffer size should be set using `client_body_buffer_size`. The property is available only in the `js_content` directive.



`r.requestText`
: The same as `r.requestBuffer`, but returns a `string`. Note that it may convert bytes invalid in UTF-8 encoding into the replacement character.



`r.rawHeadersIn[]`
: Returns an array of key-value pairs exactly as they were received from the client (0.4.1).
  

  For example, with the following request headers:
  

  ```text
  Host: localhost
  Foo:  bar
  foo:  bar2
  ```
  

  the output of `r.rawHeadersIn` will be:
  

  ```javascript
  [
      ['Host', 'localhost'],
      ['Foo', 'bar'],
      ['foo', 'bar2']
  ]
  ```
  

  All `foo` headers can be collected with the syntax:
  

  ```javascript
  r.rawHeadersIn.filter(v=>v[0].toLowerCase() == 'foo').map(v=>v[1])
  ```
  

  the output will be:
  

  ```javascript
  ['bar', 'bar2']
  ```
  

  Header field names are not converted to lower case, duplicate field values are not merged.



`r.rawHeadersOut[]`
: Returns an array of key-value pairs of response headers (0.4.1). Header field names are not converted to lower case, duplicate field values are not merged.



`r.responseBody`
: The property was deprecated in 0.5.0 and was removed in 0.8.0. The `r.responseBuffer` or `r.responseText` property should be used instead.



`r.responseBuffer`
: Contains the subrequest response body, read-only (since 0.5.0). The size of `r.responseBuffer` is limited by the `subrequest_output_buffer_size` directive.



`r.responseText`
: The same as `r.responseBuffer` but returns a string (since 0.5.0). Note that it may convert bytes invalid in UTF-8 encoding into the replacement character.



`r.return(status[, string | Buffer])`
: Sends the entire response with the specified `status` to the client. The response can be a string or Buffer (0.5.0).
  

  It is possible to specify either a redirect URL (for codes 301, 302, 303, 307, and 308) or the response body text (for other codes) as the second argument.



`r.send(string | Buffer)`
: Sends a part of the response body to the client. The data sent can be a string or Buffer (0.5.0).



`r.sendBuffer(data[, options])`
: Adds data to the chain of data chunks to be forwarded to the next body filter (0.5.2). The actual forwarding happens later, when all the data chunks of the current chain are processed.
  

  The data can be a string or Buffer. The `options` is an object used to override Angie buffer flags derived from an incoming data chunk buffer. The flags can be overridden with the following flags:
  

  `last`
  : Boolean, `true` if the buffer is the last buffer.
  

  `flush`
  : Boolean, `true` if the buffer should have the `flush` flag.
  

  The method may be called only from the `js_body_filter` function.



`r.sendHeader()`
: Sends the HTTP headers to the client.



`r.setReturnValue(value)`
: Sets the return value of the `js_set` handler (0.7.0). Unlike an ordinary return statement, this method should be used when the handler is a JS async function. For example:
  

  ```javascript
  async function js_set(r) {
      const digest = await crypto.subtle.digest('SHA-256', r.headersIn.host);
      r.setReturnValue(digest);
  }
  ```



`r.status`
: Status, writable.



`r.subrequest(uri[, options[, callback]])`
: Creates a subrequest with the given `uri` and `options`, and installs an optional completion `callback`.
  

  A subrequest shares its input headers with the client request. To send headers different from original headers to a proxied server, the `proxy_set_header` directive can be used. To send a completely new set of headers to a proxied server, the `proxy_pass_request_headers` directive can be used.
  

  If `options` is a string, then it holds the subrequest arguments string. Otherwise, `options` is expected to be an object with the following keys:
  

  `args`
  : Arguments string, by default an empty string is used.
  

  `body`
  : Request body, by default the request body of the parent request object is used.
  

  `method`
  : HTTP method, by default the `GET` method is used.
  

  `detached`
  : Boolean flag (0.3.9); if `true`, the created subrequest is a detached subrequest. Responses to detached subrequests are ignored. Unlike ordinary subrequests, a detached subrequest can be created inside a variable handler. The `detached` flag and callback argument are mutually exclusive.
  

  The completion `callback` receives a subrequest response object with methods and properties identical to the parent request object.
  

  Since 0.3.8, if a `callback` is not provided, the `Promise` object that resolves to the subrequest response object is returned.
  

  For example, to view all response headers in the subrequest:
  

  ```javascript
  async function handler(r) {
      const reply = await r.subrequest('/path');
  

      for (const h in reply.headersOut) {
          r.log(`${h}: ${reply.headersOut[h]}`);
      }
  

      r.return(200);
  }
  ```



`r.uri`
: Current URI in request, normalized, read-only.



`r.rawVariables{}`
: Angie variables as Buffers, writable (since 0.5.0).



`r.variables{}`
: Angie variables object, writable (since 0.2.8).
  

  For example, to get the `$foo` variable, one of the following syntax can be used:
  

  ```javascript
  r.variables['foo']
  r.variables.foo
  ```
  

  Since 0.8.6, regular expression captures can be accessed using the following syntax:
  

  ```javascript
  r.variables['1']
  r.variables[1]
  ```
  

  Angie treats variables referenced in `angie.conf` and unreferenced variables differently. When a variable is referenced, it may be cacheable, but when it is unreferenced, it is always uncacheable. For example, when the `$request_id` variable is only accessed from NJS, it has a new value every time it is evaluated. But, when the `$request_id` is referenced, for example:
  

  ```nginx
  proxy_set_header X-Request-Id $request_id;
  ```
  

  the `r.variables.request_id` returns the same value every time.
  

  A variable is writable if:
  

  - it was created using the `js_var` directive for HTTP or Stream (since 0.5.3)
  - it is referenced in Angie configuration file
  

  Even so, some embedded variables still cannot be assigned a value (for example, `$http_`).



`r.warn(string)`
: Writes a `string` to the error log on the `warning` level of logging.
  

  #### NOTE
  As Angie has a hardcoded maximum line length limit, only the first 2048 bytes of the string can be logged.



### Stream Session

- `s.allow()`
- `s.decline()`
- `s.deny()`
- `s.done()`
- `s.error()`
- `s.log()`
- `s.off()`
- `s.on()`
- `s.remoteAddress`
- `s.rawVariables{}`
- `s.send()`
- `s.sendDownstream()`
- `s.sendUpstream()`
- `s.status`
- `s.setReturnValue()`
- `s.variables{}`
- `s.warn()`

The stream session object is available only in the [Stream JS](https://en.angie.software//angie/docs/configuration/modules/external-modules/stream_js.md#stream-js) module. Before 0.8.5, all string properties of the object were byte strings.



`s.allow()`
: An alias to `s.done(0)` (0.2.4).



`s.decline()`
: An alias to `s.done(-5)` (0.2.4).



`s.deny()`
: An alias to `s.done(403)` (0.2.4).



`s.done([code])`
: Sets an exit `code` for the current phase handler to a code value, by default `0`. The actual finalization happens when the js handler is completed and all pending events, for example, from `ngx.fetch()` or `setTimeout()`, are processed (0.2.4).
  

  Possible code values:
  

  - `0` — successful finalization, passing control to the next phase
  - `-5` — undecided, passing control to the next handler of the current phase (if any)
  - `403` — access is forbidden
  

  May be called only from a phase handler function: `js_access` or `js_preread`.



`s.error(string)`
: Writes a sent `string` to the error log on the `error` level of logging.
  

  #### NOTE
  As Angie has a hardcoded maximum line length limit, only the first 2048 bytes of the string can be logged.



`s.log(string)`
: Writes a sent `string` to the error log on the `info` level of logging.
  

  #### NOTE
  As Angie has a hardcoded maximum line length limit, only the first 2048 bytes of the string can be logged.



`s.off(eventName)`
: Unregisters the callback set by the `s.on()` method (0.2.4).



`s.on(event, callback)`
: Registers a `callback` for the specified `event` (0.2.4).
  

  An `event` may be one of the following strings:
  

  `upload`
  : New data (string) from a client.
  

  `download`
  : New data (string) to a client.
  

  `upstream`
  : New data (Buffer) from a client (since 0.5.0).
  

  `downstream`
  : New data (Buffer) to a client (since 0.5.0).
  

  The completion callback has the following prototype: `callback(data, flags)`, where `data` is string or Buffer (depending on the event type); `flags` is an object with the following properties:
  

  `last`
  : A boolean value, `true` if data is a last buffer.



`s.remoteAddress`
: Client address, read-only.



`s.rawVariables`
: Angie variables as Buffers, writable (since 0.5.0).



`s.send(data[, options])`
: Adds data to the chain of data chunks that will be forwarded in the forward direction: in download callback to a client; in upload to an upstream server (0.2.4). The actual forwarding happens later, when all the data chunks of the current chain are processed.
  

  The data can be a string or Buffer (0.5.0). The `options` is an object used to override Angie buffer flags derived from an incoming data chunk buffer. The flags can be overridden with the following flags:
  

  `last`
  : Boolean, `true` if the buffer is the last buffer.
  

  `flush`
  : Boolean, `true` if the buffer should have the `flush` flag.
  

  The method can be called multiple times per callback invocation.



`s.sendDownstream()`
: Identical to `s.send()`, except for it always sends data to a client (since 0.7.8).



`s.sendUpstream()`
: Identical to `s.send()`, except for it always sends data from a client (since 0.7.8).



`s.status`
: Session status code, an alias to the `$status` variable, read-only (since 0.5.2).



`s.setReturnValue(value)`
: Sets the return value of the `js_set` handler (0.7.0). Unlike an ordinary return statement, this method should be used when the handler is a JS async function. For example:
  

  ```javascript
  async function js_set(r) {
      const digest = await crypto.subtle.digest('SHA-256', r.headersIn.host);
      r.setReturnValue(digest);
  }
  ```



`s.variables{}`
: Angie variables object, writable (since 0.2.8). A variable can be writable only if it is referenced in the Angie configuration file. Even so, some embedded variables still cannot be assigned a value.



`s.warn(string)`
: Writes the sent `string` to the error log on the `warning` logging level.
  

  #### NOTE
  As Angie has a hardcoded maximum line length limit, only the first 2048 bytes of the string can be logged.



### Periodic Session

- `PeriodicSession.rawVariables{}`
- `PeriodicSession.variables{}`

The `Periodic Session` object is provided as the first argument for the `js_periodic` handler for HTTP and Stream (since 0.8.1).

`PeriodicSession.rawVariables{}`
: Angie variables as Buffers, writable.

`PeriodicSession.variables{}`
: Angie variables object, writable.



### Headers

- `Headers()`
- `Headers.append()`
- `Headers.delete()`
- `Headers.get()`
- `Headers.getAll()`
- `Headers.forEach()`
- `Headers.has()`
- `Headers.set()`

The `Headers` interface of the Fetch API is available since 0.5.1.

A new `Headers` object can be created using the `Headers()` constructor (since 0.7.10):

`Headers([init])`
: `init`
  : An object containing HTTP headers for prepopulating the `Headers` object, can be a `string`, an `array` of name-value pairs, or an existing `Headers` object.

A new `Headers` object can be created with the following properties and methods:

`append()`
: Appends a new value into an existing header in the `Headers` object, or adds the header if it does not already exist (since 0.7.10).

`delete()`
: Deletes a header from the `Headers` object (since 0.7.10).

`get()`
: Returns a string containing the values of all headers with the specified name separated by a comma and a space.

`getAll(name)`
: Returns an array containing the values of all headers with the specified name.

`forEach()`
: Executes a provided function once for each key/value pair in the `Headers` object (since 0.7.10).

`has()`
: Returns a boolean value indicating whether a header with the specified name exists.

`set()`
: Sets a new value for an existing header inside the `Headers` object, or adds the header if it does not already exist (since 0.7.10).



### Request

- `Request()`
- `Request.arrayBuffer()`
- `Request.bodyUsed`
- `Request.cache`
- `Request.credentials`
- `Request.headers`
- `Request.json()`
- `Request.method`
- `Request.mode`
- `Request.text()`
- `Request.url`

The `Request` interface of the Fetch API is available since 0.7.10.

A new `Request` object can be created using the `Request()` constructor:

`Request[resource[, options]])`
: Creates a `Request` object to fetch that can be passed later to `ngx.fetch()`. The `resource` can be a URL or an existing `Request` object. The `options` is an optional argument that is expected to be an object with the following keys:
  

  `body`
  : The request body, by default is empty.
  

  `headers`
  : The response headers object — the object containing HTTP headers for prepopulating the `Headers` object, can be a `string`, an `array` of name-value pairs, or an existing `Headers` object.
  

  `method`
  : The HTTP method, by default the GET method is used.

A new `Request` object can be created with the following properties and methods:

`arrayBuffer()`
: Returns a `Promise` that resolves with an `ArrayBuffer`.

`bodyUsed`
: A boolean value, `true` if the body was used in the request.

`cache`
: Contains the cache mode of the request.

`credentials`
: Contains the credentials of the request, by default is `same-origin`.

`headers`
: The `Headers` read-only object associated with the `Request`.

`json()`
: Returns a `Promise` that resolves with the result of parsing the request body as JSON.

`method`
: Contains the request method.

`mode`
: Contains the mode of the request.

`text()`
: Returns a `Promise` that resolves with a string representation of the request body.

`url`
: Contains the URL of the request.



### Response

- `Response()`
- `Response.arrayBuffer()`
- `Response.bodyUsed`
- `Response.headers`
- `Response.json()`
- `Response.ok`
- `Response.redirected`
- `Response.status`
- `Response.statusText`
- `Response.text()`
- `Response.type`
- `Response.url`

The `Response` interface is available since 0.5.1.

A new `Response` object can be created using the `Response()` constructor (since 0.7.10):

`Response[body[, options]])`
: Creates a `Response` object. The `body` is an optional argument, can be a `string` or a `buffer`, by default is `null`. The `options` is an optional argument that is expected to be an object with the following keys:
  

  `headers`
  : The response headers object — the object containing HTTP headers for prepopulating the `Headers` object, can be a `string`, an `array` of name-value pairs, or an existing `Headers` object.
  

  `status`
  : The status code of the response.
  

  `statusText`
  : The status message corresponding to the status code.

A new `Response()` object can be created with the following properties and methods:

`arrayBuffer()`
: Takes a `Response` stream and reads it to completion. Returns a `Promise` that resolves with an `ArrayBuffer`.

`bodyUsed`
: A boolean value, `true` if the body was read.

`headers`
: The `Headers` read-only object associated with the `Response`.

`json()`
: Takes a `Response` stream and reads it to completion. Returns a `Promise` that resolves with the result of parsing the body text as JSON.

`ok`
: A boolean value, `true` if the response was successful (status codes between 200–299).

`redirected`
: A boolean value, `true` if the response is the result of a redirect.

`status`
: The status code of the response.

`statusText`
: The status message corresponding to the status code.

`text()`
: Takes a `Response` stream and reads it to completion. Returns a `Promise` that resolves with a string.

`type`
: The type of the response.

`url`
: The URL of the response.



### ngx

- `ngx.build`
- `ngx.conf_file_path`
- `ngx.conf_prefix`
- `ngx.error_log_path`
- `ngx.fetch()`
- `ngx.log()`
- `ngx.prefix`
- `ngx.version`
- `ngx.version_number`
- `ngx.worker_id`

The `ngx` global object is available since 0.5.0.

`ngx.build`
: A string containing an optional Angie build name, corresponds to the `--build=`name argument of the configure script, by default is `""` (0.8.0).

`ngx.conf_file_path`
: A string containing the file path to current Angie configuration file (0.8.0).

`ngx.conf_prefix`
: A string containing the file path to Angie configuration prefix — the directory where Angie is currently looking for configuration (0.7.8).

`ngx.error_log_path`
: A string containing the file path to the current error log file (0.8.0).



`ngx.fetch(resource, [options])`
: Makes a request to fetch a `resource` (0.5.1), which can be a URL or the `Request` object (0.7.10). Returns a `Promise` that resolves with the `Response` object. Since 0.7.0, the `https://` scheme is supported; redirects are not handled.
  

  If the URL in the `resource` is specified as a domain name, it is resolved using a resolver. If the `https://` scheme is specified, the `js_fetch_trusted_certificate` directive should be configured for the authentication of the `resource`'s HTTPS server.
  

  The `options` parameter is expected to be an object with the following keys:
  

  `body`
  : Request body, by default is empty.
  

  `buffer_size`
  : The buffer size for reading the response, by default is `4096`.
  

  `headers`
  : Request headers object.
  

  `max_response_body_size`
  : The maximum size of the response body in bytes, by default is `32768`.
  

  `method`
  : HTTP method, by default the `GET` method is used.
  

  `verify`
  : Enables or disables verification of the HTTPS server certificate, by default is `true` (0.7.0).
  

  Example:
  

  ```javascript
  let reply = await ngx.fetch('http://example.com/');
  let body = await reply.text();
  

  r.return(200, body);
  ```

`ngx.log(level, message)`
: Writes a message to the error log with the specified level of logging. The `level` parameter specifies one of the log levels; the `message` parameter can be a string or Buffer. The following log levels can be specified: `ngx.INFO`, `ngx.WARN`, and `ngx.ERR`.
  

  #### NOTE
  As Angie has a hardcoded maximum line length limit, only the first 2048 bytes of the string can be logged.

`ngx.prefix`
: A string containing the file path to Angie prefix — a directory that keeps server files (0.8.0).

`ngx.version`
: A string containing Angie version, for example: `1.25.0` (0.8.0).

`ngx.version_number`
: A number containing Angie version, for example: `1025000` (0.8.0).

`ngx.worker_id`
: A number that corresponds to Angie internal worker ID, the value is between `0` and the value specified in the `worker_processes` directive (0.8.0).



### ngx.shared

The `ngx.shared` global object is available since 0.8.0.



#### SharedDict

- `ngx.shared.SharedDict.add()`
- `ngx.shared.SharedDict.capacity`
- `ngx.shared.SharedDict.clear()`
- `ngx.shared.SharedDict.delete()`
- `ngx.shared.SharedDict.freeSpace()`
- `ngx.shared.SharedDict.get()`
- `ngx.shared.SharedDict.has()`
- `ngx.shared.SharedDict.incr()`
- `ngx.shared.SharedDict.items()`
- `ngx.shared.SharedDict.keys()`
- `ngx.shared.SharedDict.name`
- `ngx.shared.SharedDict.pop()`
- `ngx.shared.SharedDict.replace()`
- `ngx.shared.SharedDict.set()`
- `ngx.shared.SharedDict.size()`
- `ngx.shared.SharedDict.type`

The shared dictionary object is available since 0.8.0. The shared dictionary name, type, and size are set with the `js_shared_dict_zone` directive in HTTP or Stream.

A `SharedDict()` object has the following properties and methods:

`ngx.shared.SharedDict.add(key, value [,timeout])`
: Sets the `value` for the specified `key` in the dictionary only if the key does not exist yet. The `key` argument is a string representing the key of the item to add; the `value` argument is the value of the item to add.
  

  The optional `timeout` argument is specified in milliseconds and overrides the `timeout` parameter of the `js_shared_dict_zone` directive in HTTP or Stream (since 0.8.5). It can be useful when some keys are expected to have unique timeouts.
  

  Returns `true` if the value has been successfully added to the `SharedDict` dictionary; `false` if the key already exists in the dictionary. Throws `SharedMemoryError` if there is not enough free space in the `SharedDict` dictionary. Throws `TypeError` if the `value` is of a different type than expected by this dictionary.

`ngx.shared.SharedDict.capacity`
: Returns the capacity of the `SharedDict` dictionary, corresponds to the `size` parameter of the `js_shared_dict_zone` directive in HTTP or Stream.

`ngx.shared.SharedDict.clear()`
: Removes all items from the `SharedDict` dictionary.

`ngx.shared.SharedDict.delete(key)`
: Removes the item associated with the specified key from the `SharedDict` dictionary; `true` if the item in the dictionary existed and was removed, `false` otherwise.

`ngx.shared.SharedDict.freeSpace()`
: Returns the free page size in bytes. If the size is zero, the `SharedDict` dictionary will still accept new values if there is space in the occupied pages.

`ngx.shared.SharedDict.get(key)`
: Retrieves the item by its `key`; returns the value associated with the `key` or `undefined` if there is none.

`ngx.shared.SharedDict.has(key)`
: Searches for an item by its `key`; returns `true` if such item exists or `false` otherwise.

`ngx.shared.SharedDict.incr(key,delta[[,init], timeout])`
: Increments the integer value associated with the `key` by `delta`. The `key` argument is a string; the `delta` argument is the number to increment or decrement the value by. If the key does not exist, the item will be initialized to the optional `init` argument, by default is `0`.
  

  The optional `timeout` argument is specified in milliseconds and overrides the `timeout` parameter of the `js_shared_dict_zone` directive in HTTP or Stream (since 0.8.5). It can be useful when some keys are expected to have unique timeouts.
  

  Returns the new value. Throws `SharedMemoryError` if there is not enough free space in the `SharedDict` dictionary. Throws `TypeError` if this dictionary does not expect numbers.
  

  #### NOTE
  This method can be used only if the dictionary type was declared with the `type=number` parameter of the `js_shared_dict_zone` directive in HTTP or Stream.

`ngx.shared.SharedDict.items([maxCount])`
: Returns an array of the `SharedDict` dictionary key-value items (since 0.8.1). The `maxCount` parameter sets the maximum number of items to retrieve, by default is `1024`.

`ngx.shared.SharedDict.keys([maxCount])`
: Returns an array of the `SharedDict` dictionary keys. The `maxCount` parameter sets the maximum number of keys to retrieve, by default is `1024`.

`ngx.shared.SharedDict.name`
: Returns the name of the `SharedDict` dictionary, corresponds to the `zone=` parameter of the `js_shared_dict_zone` directive in HTTP or Stream.

`ngx.shared.SharedDict.pop(key)`
: Removes the item associated with the specified `key` from the `SharedDict` dictionary; returns the value associated with the `key` or `undefined` if there is none.

`ngx.shared.SharedDict.replace(key, value)`
: Replaces the `value` for the specified `key` only if the key already exists; returns `true` if the value was successfully replaced, `false` if the key does not exist in the `SharedDict` dictionary. Throws `SharedMemoryError` if there is not enough free space in the `SharedDict` dictionary. Throws `TypeError` if the `value` is of a different type than expected by this dictionary.

`ngx.shared.SharedDict.set(key, value [,timeout])`
: Sets the `value` for the specified `key`; returns this `SharedDict` dictionary (for method chaining).
  

  The optional `timeout` argument is specified in milliseconds and overrides the `timeout` parameter of the `js_shared_dict_zone` directive in HTTP or Stream (since 0.8.5). It can be useful when some keys are expected to have unique timeouts.

`ngx.shared.SharedDict.size()`
: Returns the number of items for the `SharedDict` dictionary.

`ngx.shared.SharedDict.type`
: Returns `string` or `number` that corresponds to the `SharedDict` dictionary type set by the `type=` parameter of the `js_shared_dict_zone` directive in HTTP or Stream.



## Built-in Objects



### console

- `console.error()`
- `console.info()`
- `console.log()`
- `console.time()`
- `console.timeEnd()`
- `console.warn()`

The `console` object is available in Angie since 0.8.2, in CLI since 0.2.6.

`console.error(msg[, msg2 ...])`
: Outputs one or more error messages. The message may be a string or an object.

`console.info(msg[, msg2 ...])`
: Outputs one or more info messages. The message may be a string or an object.

`console.log(msg[, msg2 ...])`
: Outputs one or more log messages. The message may be a string or an object.

`console.time(label)`
: Starts a timer that can track how long an operation takes. The `label` parameter allows naming different timers. If `console.timeEnd()` is called with the same name, the time that elapsed since the timer was started will be output, in milliseconds.

`console.timeEnd(label)`
: Stops a timer previously started by `console.time()`. The `label` parameter allows naming different timers.

`console.warn(msg[, msg2 ...])`
: Outputs one or more warning messages. The message may be a string or an object.



### crypto

- `crypto.getRandomValues()`
- `crypto.subtle.encrypt()`
- `crypto.subtle.decrypt()`
- `crypto.subtle.deriveBits()`
- `crypto.subtle.deriveKey()`
- `crypto.subtle.digest()`
- `crypto.subtle.exportKey()`
- `crypto.subtle.generateKey()`
- `crypto.subtle.importKey()`
- `crypto.subtle.sign()`
- `crypto.subtle.verify()`

The `crypto` object is a global object that allows using cryptographic functionality (since 0.7.0).

`crypto.getRandomValues(typedArray)`
: Gets cryptographically strong random values. Returns the same array passed as `typedArray` but with its contents replaced with the newly generated random numbers. Possible values:
  

  `typedArray`
  : Can be `Int8Array`, `Int16Array`, `Uint16Array`, `Int32Array`, or `Uint32Array`.

`crypto.subtle.encrypt(algorithm, key, data)`
: Encrypts `data` using the provided `algorithm` and `key`. Returns a `Promise` that fulfills with an `ArrayBuffer` containing the ciphertext. Possible values:
  

  `algorithm`
  : An object that specifies the algorithm to be used and any extra parameters if required:
    

    - For `RSA-OAEP`, pass an object with the following keys:
    

      `name`
      : A string, should be set to `RSA-OAEP`:
        ```javascript
        crypto.subtle.encrypt({name: "RSA-OAEP"}, key, data)
        ```
    - For `AES-CTR`, pass an object with the following keys:
    

      `name`
      : A string, should be set to `AES-CTR`.
    

      `counter`
      : An `ArrayBuffer`, `TypedArray`, or `DataView` — the initial value of the counter block, must be 16 bytes long (the AES block size). The rightmost length bits of this block are used for the counter, and the rest is used for the nonce. For example, if length is set to 64, then the first half of counter is the nonce and the second half is used for the counter.
    

      `length`
      : The number of bits in the counter block that are used for the actual counter. The counter must be big enough that it doesn't wrap.
    - For `AES-CBC`, pass an object with the following keys:
    

      `name`
      : A string, should be set to `AES-CBC`.
    

      `iv`
      : The initialization vector, is an `ArrayBuffer`, `TypedArray`, or `DataView`, must be 16 bytes, unpredictable, and preferably cryptographically random. However, it need not be secret, for example, it may be transmitted unencrypted along with the ciphertext.
    - For `AES-GCM`, pass an object with the following keys:
    

      `name`
      : A string, should be set to `AES-GCM`.
    

      `iv`
      : The initialization vector, is an `ArrayBuffer`, `TypedArray`, or `DataView`, must be 16 bytes, and must be unique for every encryption operation carried out with a given key.
    

      `additionalData`
      : (optional) is an `ArrayBuffer`, `TypedArray`, or `DataView` that contains additional data that will not be encrypted but will be authenticated along with the encrypted data. If `additionalData` is specified, then the same data must be specified in the corresponding call to `decrypt()`: if the data given to the `decrypt()` call does not match the original data, the decryption will throw an exception. The bit length of `additionalData` must be smaller than `2^64 - 1`.
    

      `tagLength`
      : (optional, default is `128`) - a `number` that determines the size in bits of the authentication tag generated in the encryption operation and used for authentication in the corresponding decryption. Possible values: `32`, `64`, `96`, `104`, `112`, `120`, or `128`. The AES-GCM specification recommends that it should be `96`, `104`, `112`, `120`, or `128`, although `32` or `64` bits may be acceptable in some applications.
  

  `key`
  : A `CryptoKey` that contains the key to be used for encryption.
  

  `data`
  : An `ArrayBuffer`, `TypedArray`, or `DataView` that contains the data to be encrypted (also known as the plaintext).

`crypto.subtle.decrypt(algorithm, key, data)`
: Decrypts encrypted data. Returns a `Promise` with the decrypted data. Possible values:
  

  `algorithm`
  : An object that specifies the algorithm to be used, and any extra parameters as required. The values given for the extra parameters must match those passed into the corresponding `encrypt()` call.
    

    - For `RSA-OAEP`, pass an object with the following keys:
    

      `name`
      : A string, should be set to `RSA-OAEP`:
        ```javascript
        crypto.subtle.encrypt({name: "RSA-OAEP"}, key, data)
        ```
    - For `AES-CTR`, pass an object with the following keys:
    

      `name`
      : A string, should be set to `AES-CTR`.
    

      `counter`
      : An `ArrayBuffer`, `TypedArray`, or `DataView` — the initial value of the counter block, must be 16 bytes long (the AES block size). The rightmost length bits of this block are used for the counter, and the rest is used for the nonce. For example, if length is set to 64, then the first half of counter is the nonce and the second half is used for the counter.
    

      `length`
      : The number of bits in the counter block that are used for the actual counter. The counter must be big enough that it doesn't wrap.
    - For `AES-CBC`, pass an object with the following keys:
    

      `name`
      : A string, should be set to `AES-CBC`.
    

      `iv`
      : The initialization vector, is an `ArrayBuffer`, `TypedArray`, or `DataView`, must be 16 bytes, unpredictable, and preferably cryptographically random. However, it need not be secret (for example, it may be transmitted unencrypted along with the ciphertext).
    - For `AES-GCM`, pass an object with the following keys:
    

      `name`
      : A string, should be set to `AES-GCM`.
    

      `iv`
      : The initialization vector, is an `ArrayBuffer`, `TypedArray`, or `DataView`, must be 16 bytes, and must be unique for every encryption operation carried out with a given key.
    

      `additionalData`
      : (optional) is an `ArrayBuffer`, `TypedArray`, or `DataView` that contains additional data that will not be encrypted but will be authenticated along with the encrypted data. If `additionalData` is specified, then the same data must be specified in the corresponding call to `decrypt()`: if the data given to the `decrypt()` call does not match the original data, the decryption will throw an exception. The bit length of `additionalData` must be smaller than `2^64 - 1`.
    

      `tagLength`
      : (optional, default is `128`) - a `number` that determines the size in bits of the authentication tag generated in the encryption operation and used for authentication in the corresponding decryption. Possible values: `32`, `64`, `96`, `104`, `112`, `120`, or `128`. The AES-GCM specification recommends that it should be `96`, `104`, `112`, `120`, or `128`, although `32` or `64` bits may be acceptable in some applications.
  

  `key`
  : A `CryptoKey` that contains the key to be used for decryption. If `RSA-OAEP` is used, this is the `privateKey` property of the `CryptoKeyPair` object.
  

  `data`
  : An `ArrayBuffer`, `TypedArray`, or `DataView` that contains the data to be decrypted (also known as ciphertext).

`crypto.subtle.deriveBits(algorithm, baseKey, length)`
: Derives an array of bits from a base key. Returns a `Promise` which will be fulfilled with an `ArrayBuffer` containing the derived bits. Possible values:
  

  `algorithm`
  : An object that defines the derivation algorithm to use:
    

    - For `HKDF`, pass an object with the following keys:
    

      `name`
      : A string, should be set to `HKDF`.
    

      `hash`
      : A string with the digest algorithm to use: `SHA-1`, `SHA-256`, `SHA-384`, or `SHA-512`.
    

      `salt`
      : An `ArrayBuffer`, `TypedArray`, or `DataView` that represents a random or pseudo-random value with the same length as the output of the `digest` function. Unlike the input key material passed into `deriveKey()`, salt does not need to be kept secret.
    

      `info`
      : An `ArrayBuffer`, `TypedArray`, or `DataView` that represents application-specific contextual information used to bind the derived key to an application or context, and enables deriving different keys for different contexts while using the same input key material. This property is required but may be an empty buffer.
    - For `PBKDF2`, pass an object with the following keys:
    

      `name`
      : A string, should be set to `PBKDF2`.
    

      `hash`
      : A string with the digest algorithm to use: `SHA-1`, `SHA-256`, `SHA-384`, or `SHA-512`.
    

      `salt`
      : An `ArrayBuffer`, `TypedArray`, or `DataView` that represents random or pseudo-random value of at least `16` bytes. Unlike the input key material passed into `deriveKey()`, salt does not need to be kept secret.
    

      `iterations`
      : A `number` that represents the number of times the hash function will be executed in `deriveKey()`.
    - For `ECDH`, pass the object with the following keys (since 0.9.1):
    

      `name`
      : A string, should be set to `ECDH`.
    

      `public`
      : A `CryptoKey` that represents the public key of the other party. The key must be generated using the same curve as the base key.
  

  `baseKey`
  : A `CryptoKey` that represents the input to the derivation algorithm - the initial key material for the derivation function: for example, for `PBKDF2` it might be a password, imported as a `CryptoKey` using `crypto.subtle.importKey()`.
  

  `length`
  : A number representing the number of bits to derive. For browser compatibility, the number should be a multiple of `8`.

`crypto.subtle.deriveKey(algorithm, baseKey, derivedKeyAlgorithm, extractable, keyUsages)`
: Derives a secret key from a master key. Possible values:
  

  `algorithm`
  : An object that defines the derivation algorithm to use:
    

    - For `HKDF`, pass the object with the following keys:
    

      `name`
      : A string, should be set to `HKDF`.
    

      `hash`
      : A string with the digest algorithm to use: `SHA-1`, `SHA-256`, `SHA-384`, or `SHA-512`.
    

      `salt`
      : An `ArrayBuffer`, `TypedArray`, or `DataView` that represents random or pseudo-random value with the same length as the output of the `digest` function. Unlike the input key material passed into `deriveKey()`, salt does not need to be kept secret.
    

      `info`
      : An `ArrayBuffer`, `TypedArray`, or `DataView` that represents application-specific contextual information used to bind the derived key to an application or context, and enables deriving different keys for different contexts while using the same input key material. This property is required but may be an empty buffer.
    - For `PBKDF2`, pass the object with the following keys:
    

      `name`
      : A string, should be set to `PBKDF2`.
    

      `hash`
      : A string with the digest algorithm to use: `SHA-1`, `SHA-256`, `SHA-384`, or `SHA-512`.
    

      `salt`
      : An `ArrayBuffer`, `TypedArray`, or `DataView` that represents random or pseudo-random value of at least `16` bytes. Unlike the input key material passed into `deriveKey()`, salt does not need to be kept secret.
    

      `iterations`
      : A `number` that represents the number of times the hash function will be executed in `deriveKey()`.
    - For `ECDH`, pass the object with the following keys (since 0.9.1):
    

      `name`
      : A string, should be set to `ECDH`.
    

      `publicKey`
      : A `CryptoKey` that represents the public key of the other party. The key must be generated using the same curve as the base key.
  

  `baseKey`
  : A `CryptoKey` that represents the input to the derivation algorithm - the initial key material for the derivation function: for example, for `PBKDF2` it might be a password, imported as a `CryptoKey` using `crypto.subtle.importKey()`.
  

  `derivedKeyAlgorithm`
  : An object that defines the algorithm the derived key will be used for:
    

    - For `HMAC`, pass the object with the following keys:
    

      `name`
      : A string, should be set to `HMAC`.
    

      `hash`
      : A string with the name of the digest function to use: `SHA-1`, `SHA-256`, `SHA-384`, or `SHA-512`.
    

      `length`
      : (optional) is a `number` that represents the length in bits of the key. If not specified, the length of the key is equal to the block size of the chosen hash function.
    - For `AES-CTR`, `AES-CBC`, or `AES-GCM`, pass the object with the following keys:
    

      `name`
      : A string, should be set to `AES-CTR`, `AES-CBC`, or `AES-GCM`, depending on the algorithm used.
    

      `length`
      : A `number` that represents the length in bits of the key to generate: `128`, `192`, or `256`.
  

  `extractable`
  : A boolean value that indicates whether it will be possible to export the key.
  

  `keyUsages`
  : An `Array` that indicates what can be done with the derived key. The key usages must be allowed by the algorithm set in `derivedKeyAlgorithm`. Possible values:
    

    `encrypt`
    : Key for encrypting messages.
    

    `decrypt`
    : Key for decrypting messages.
    

    `sign`
    : Key for signing messages.
    

    `verify`
    : Key for verifying signatures.
    

    `deriveKey`
    : Key for deriving a new key.
    

    `deriveBits`
    : Key for deriving bits.
    

    `wrapKey`
    : Key for wrapping a key.
    

    `unwrapKey`
    : Key for unwrapping a key.

`crypto.subtle.digest(algorithm, data)`
: Generates a digest of the given data. Takes as its arguments an identifier for the digest algorithm to use and the data to digest. Returns a `Promise` which will be fulfilled with the digest. Possible values:
  

  `algorithm`
  : A string that defines the hash function to use: `SHA-1` (not for cryptographic applications), `SHA-256`, `SHA-384`, or `SHA-512`.
  

  `data`
  : An `ArrayBuffer`, `TypedArray`, or `DataView` that contains the data to be digested.

`crypto.subtle.exportKey(format, key)`
: Exports a key: takes a key as a `CryptoKey` object and returns the key in an external, portable format (since 0.7.10). If the `format` was `jwk`, then the `Promise` fulfills with a JSON object containing the key. Otherwise, the promise fulfills with an `ArrayBuffer` containing the key. Possible values:
  

  `format`
  : A string that describes the data format in which the key should be exported, can be the following:
    

    `raw`
    : The raw data format.
    

    `pkcs8`
    : The [PKCS #8](https://datatracker.ietf.org/doc/html/rfc5208) format.
    

    `spki`
    : The [SubjectPublicKeyInfo](https://datatracker.ietf.org/doc/html/rfc5280#section-4.1) format.
    

    `jwk`
    : The [JSON Web Key](https://datatracker.ietf.org/doc/html/rfc7517) (JWK) format (since 0.7.10).
  

  `key`
  : The `CryptoKey` that contains the key to be exported.

`crypto.subtle.generateKey(algorithm, extractable, usage)`
: Generates a new key for symmetric algorithms or key pair for public-key algorithms (since 0.7.10). Returns a `Promise` that fulfills with the generated key as a `CryptoKey` or `CryptoKeyPair` object. Possible values:
  

  `algorithm`
  : A dictionary object that defines the type of key to generate and provides extra algorithm-specific parameters:
    

    - For `RSASSA-PKCS1-v1_5`, `RSA-PSS`, or `RSA-OAEP`, pass the object with the following keys:
    

      `name`
      : A string, should be set to `RSASSA-PKCS1-v1_5`, `RSA-PSS`, or `RSA-OAEP`, depending on the algorithm used.
    

      `hash`
      : A string that represents the name of the `digest` function to use, can be `SHA-256`, `SHA-384`, or `SHA-512`.
    - For `ECDSA`, pass the object with the following keys:
    

      `name`
      : A string, should be set to `ECDSA`.
    

      `namedCurve`
      : A string that represents the name of the elliptic curve to use, may be `P-256`, `P-384`, or `P-521`.
    - For `HMAC`, pass the object with the following keys:
    

      `name`
      : A string, should be set to `HMAC`.
    

      `hash`
      : A string that represents the name of the `digest` function to use, can be `SHA-256`, `SHA-384`, or `SHA-512`.
    

      `length`
      : (optional) is a number that represents the length in bits of the key. If omitted, the length of the key is equal to the length of the digest generated by the chosen digest function.
    - For `AES-CTR`, `AES-CBC`, or `AES-GCM`, pass the string identifying the algorithm or an object of the form ` *"name": "ALGORITHM"* `, where `ALGORITHM` is the name of the algorithm.
    - For `ECDH`, pass the object with the following keys (since 0.9.1):
    

      `name`
      : A string, should be set to `ECDH`.
    

      `namedCurve`
      : A string that represents the name of the elliptic curve to use, may be `P-256`, `P-384`, or `P-521`.
  

  `extractable`
  : Boolean value that indicates if it is possible to export the key.
  

  `usage`
  : An `array` that indicates possible actions with the key:
    

    `encrypt`
    : Key for encrypting messages.
    

    `decrypt`
    : Key for decrypting messages.
    

    `sign`
    : Key for signing messages.
    

    `verify`
    : Key for verifying signatures.
    

    `deriveKey`
    : Key for deriving a new key.
    

    `deriveBits`
    : Key for deriving bits.
    

    `wrapKey`
    : Key for wrapping a key.
    

    `unwrapKey`
    : Key for unwrapping a key.

`crypto.subtle.importKey(format, keyData, algorithm, extractable, keyUsages)`
: Imports a key: takes as input a key in an external, portable format and gives a `CryptoKey` object. Returns a `Promise` that fulfills with the imported key as a `CryptoKey` object. Possible values:
  

  `format`
  : A string that describes the data format of the key to import, can be the following:
    

    `raw`
    : The raw data format.
    

    `pkcs8`
    : The [PKCS #8](https://datatracker.ietf.org/doc/html/rfc5208) format.
    

    `spki`
    : The [SubjectPublicKeyInfo](https://datatracker.ietf.org/doc/html/rfc5280#section-4.1) format.
    

    `jwk`
    : The [JSON Web Key](https://datatracker.ietf.org/doc/html/rfc7517) (JWK) format (since 0.7.10).
  

  `keyData`
  : The `ArrayBuffer`, `TypedArray`, or `DataView` object that contains the key in the given format.
  

  `algorithm`
  : A dictionary object that defines the type of key to import and provides extra algorithm-specific parameters:
    

    - For `RSASSA-PKCS1-v1_5`, `RSA-PSS`, or `RSA-OAEP`, pass the object with the following keys:
    

      `name`
      : A string, should be set to `RSASSA-PKCS1-v1_5`, `RSA-PSS`, or `RSA-OAEP`, depending on the used algorithm.
    

      `hash`
      : A string that represents the name of the `digest` function to use, can be `SHA-1`, `SHA-256`, `SHA-384`, or `SHA-512`.
    - For `ECDSA`, pass the object with the following keys:
    

      `name`
      : A string, should be set to `ECDSA`.
    

      `namedCurve`
      : A string that represents the name of the elliptic curve to use, may be `P-256`, `P-384`, or `P-521`.
    - For `HMAC`, pass the object with the following keys:
    

      `name`
      : A string, should be set to `HMAC`.
    

      `hash`
      : A string that represents the name of the `digest` function to use, can be `SHA-256`, `SHA-384`, or `SHA-512`.
    

      `length`
      : (optional) is a number that represents the length in bits of the key. If omitted, the length of the key is equal to the length of the digest generated by the chosen digest function.
    - For `AES-CTR`, `AES-CBC`, or `AES-GCM`, pass the string identifying the algorithm or an object of the form ` *"name": "ALGORITHM"* `, where `ALGORITHM` is the name of the algorithm.
    - For `PBKDF2`, pass the `PBKDF2` string.
    - For `HKDF`, pass the `HKDF` string.
    - For `ECDH`, pass the object with the following keys (since 0.9.1):
    

      `name`
      : A string, should be set to `ECDH`.
    

      `namedCurve`
      : A string that represents the name of the elliptic curve to use, may be `P-256`, `P-384`, or `P-521`.
  

  `extractable`
  : Boolean value that indicates if it is possible to export the key.
  

  `keyUsages`
  : An `array` that indicates possible actions with the key:
    

    `encrypt`
    : Key for encrypting messages.
    

    `decrypt`
    : Key for decrypting messages.
    

    `sign`
    : Key for signing messages.
    

    `verify`
    : Key for verifying signatures.
    

    `deriveKey`
    : Key for deriving a new key.
    

    `deriveBits`
    : Key for deriving bits.
    

    `wrapKey`
    : Key for wrapping a key.
    

    `unwrapKey`
    : Key for unwrapping a key.

`crypto.subtle.sign(algorithm, key, data)`
: Returns `signature` as a `Promise` that fulfills with an `ArrayBuffer` containing the signature. Possible values:
  

  `algorithm`
  : A string or object that specifies the signature algorithm to use and its parameters:
    

    - For `RSASSA-PKCS1-v1_5`, pass the string identifying the algorithm or an object of the form ` *"name": "ALGORITHM"* `.
    - For `RSA-PSS`, pass the object with the following keys:
    

      `name`
      : A string, should be set to `RSA-PSS`.
    

      `saltLength`
      : A long `integer` that represents the length of the random salt to use, in bytes.
    - For `ECDSA`, pass the object with the following keys:
    

      `name`
      : A string, should be set to `ECDSA`.
    

      `hash`
      : An identifier for the digest algorithm to use, can be `SHA-256`, `SHA-384`, or `SHA-512`.
    - For `HMAC`, pass the string identifying the algorithm or an object of the form ` *"name": "ALGORITHM"* `.
  

  `key`
  : A `CryptoKey` object that contains the key to be used for signing. If algorithm identifies a public-key cryptosystem, this is the private key.
  

  `data`
  : An `ArrayBuffer`, `TypedArray`, or `DataView` object that contains the data to be signed.

`crypto.subtle.verify(algorithm, key, signature, data)`
: Verifies a digital signature; returns a `Promise` that fulfills with a boolean value: `true` if the signature is valid, otherwise `false`. Possible values:
  

  `algorithm`
  : A string or object that specifies the algorithm to use and its parameters:
    

    - For `RSASSA-PKCS1-v1_5`, pass the string identifying the algorithm or an object of the form ` *"name": "ALGORITHM"* `.
    - For `RSA-PSS`, pass the object with the following keys:
    

      `name`
      : A string, should be set to `RSA-PSS`.
    

      `saltLength`
      : A long `integer` that represents the length of the random salt to use, in bytes.
    - For `ECDSA`, pass the object with the following keys:
    

      `name`
      : A string, should be set to `ECDSA`.
    

      `hash`
      : An identifier for the digest algorithm to use, can be `SHA-256`, `SHA-384`, or `SHA-512`.
    - For `HMAC`, pass the string identifying the algorithm or an object of the form ` *"name": "ALGORITHM"* `.
  

  `key`
  : A `CryptoKey` object that contains the key to be used for verifying. It is the secret key for a symmetric algorithm and the public key for a public-key system.
  

  `signature`
  : An `ArrayBuffer`, `TypedArray`, or `DataView` that contains the signature to verify.
  

  `data`
  : An `ArrayBuffer`, `TypedArray`, or `DataView` object that contains the data whose signature is to be verified.



#### CryptoKey

- `CryptoKey.algorithm`
- `CryptoKey.extractable`
- `CryptoKey.type`
- `CryptoKey.usages`

The `CryptoKey` object represents a cryptographic `key` obtained from one of the `SubtleCrypto` methods: `crypto.subtle.generateKey()`, `crypto.subtle.deriveKey()`, `crypto.subtle.importKey()`.

`CryptoKey.algorithm`
: Returns an object describing the algorithm for which this key can be used and any associated extra parameters (since 0.8.0), read-only.

`CryptoKey.extractable`
: A boolean value, `true` if the key can be exported (since 0.8.0), read-only.

`CryptoKey.type`
: A string value that indicates which kind of key is represented by the object, read-only. Possible values:
  

  `secret`
  : This key is a secret key for use with a symmetric algorithm.
  

  `private`
  : This key is the private half of an asymmetric algorithm's `CryptoKeyPair`.
  

  `public`
  : This key is the public half of an asymmetric algorithm's `CryptoKeyPair`.

`CryptoKey.usages`
: An array of strings indicating what this key can be used for (since 0.8.0), read-only. Possible array values:
  

  `encrypt`
  : Key for encrypting messages.
  

  `decrypt`
  : Key for decrypting messages.
  

  `sign`
  : Key for signing messages.
  

  `verify`
  : Key for verifying signatures.
  

  `deriveKey`
  : Key for deriving a new key.
  

  `deriveBits`
  : Key for deriving bits.



#### CryptoKeyPair

- `CryptoKeyPair.privateKey`
- `CryptoKeyPair.publicKey`

The `CryptoKeyPair` is a dictionary object of the WebCrypto API that represents an asymmetric key pair.

`CryptoKeyPair.privateKey`
: A `CryptoKey` object representing the private key.

`CryptoKeyPair.publicKey`
: A `CryptoKey` object representing the public key.



### njs

- `njs.version`
- `njs.version_number`
- `njs.dump()`
- `njs.memoryStats`
- `njs.on()`

The `njs` object is a global object that represents the current VM instance (since 0.2.0).

`njs.version`
: Returns a string with the current version of NJS (for example, "0.7.4").

`njs.version_number`
: Returns a number with the current version of NJS. For example, "0.7.4" is returned as `0x000704` (since 0.7.4).

`njs.dump(value)`
: Returns the pretty-print string representation for a value.

`njs.memoryStats`
: Object containing memory statistics for the current VM instance (since 0.7.8).
  

  `size`
  : Amount of memory in bytes NJS memory pool claimed from the operating system.

`njs.on(event, callback)`
: Registers a callback for the specified VM event (since 0.5.2). An event may be one of the following strings:
  

  `exit`
  : Is called before the VM is destroyed. The callback is called without arguments.



### process

- `process.argv`
- `process.env`
- `process.kill()`
- `process.pid`
- `process.ppid`

The `process` object is a global object that provides information about the current process (0.3.3).

`process.argv`
: Returns an array that contains the command-line arguments passed when the current process was launched.

`process.env`
: Returns an object containing the user environment.
  

  #### NOTE
  By default, Angie removes all environment variables inherited from its parent process except the TZ variable. Use the `env` directive to preserve some of the inherited variables.

`process.kill(pid, number | string)`
: Sends the signal to the process identified by `pid`. Signal names are numbers or strings such as `SIGINT` or `SIGHUP`. See [kill(2)](https://man7.org/linux/man-pages/man2/kill.2.html) for more information.

`process.pid`
: Returns the PID of the current process.

`process.ppid`
: Returns the PID of the current parent process.



### String

By default, all strings in NJS are Unicode strings. They correspond to ECMAScript strings that contain Unicode characters. Before 0.8.0, byte strings were also supported.



#### Byte Strings (Removed)

#### NOTE
Since 0.8.0, the support for byte strings and byte string methods was removed. When working with byte sequences, the [Buffer](#njs-buffer) object and Buffer properties, such as `r.requestBuffer`, `r.rawVariables`, should be used.

Byte strings contained a sequence of bytes and were used to serialize Unicode strings to external data and deserialize from external sources. For example, the `toUTF8()` method serialized a Unicode string to a byte string using UTF-8 encoding. The `toBytes()` method serialized a Unicode string with code points up to 255 into a byte string; otherwise, `null` was returned.

The following methods were made obsolete and removed in 0.8.0:

- `String.bytesFrom()` (removed in 0.8.0, use `Buffer.from()`)
- `String.prototype.fromBytes()` (removed in 0.8.0)
- `String.prototype.fromUTF8()` (removed in 0.8.0, use `TextDecoder`)
- `String.prototype.toBytes()` (removed in 0.8.0)
- `String.prototype.toString()` with encoding (removed in 0.8.0)
- `String.prototype.toUTF8()` (removed in 0.8.0, use `TextEncoder`)



## Web API



### TextDecoder

- `TextDecoder()`
- `TextDecoder.prototype.encoding`
- `TextDecoder.prototype.fatal`
- `TextDecoder.prototype.ignoreBOM`
- `TextDecoder.prototype.decode()`

The `TextDecoder` produces a stream of code points from a stream of bytes (0.4.3).

`TextDecoder([[encoding], options])`
: Creates a new `TextDecoder` object for the specified `encoding`; currently, only UTF-8 is supported. The `options` is a `TextDecoderOptions` dictionary with the property:
  

  `fatal`
  : Boolean flag indicating if `TextDecoder.decode()` must throw the `TypeError` exception when a coding error is found, by default is `false`.

`TextDecoder.prototype.encoding`
: Returns a string with the name of the encoding used by `TextDecoder()`, read-only.

`TextDecoder.prototype.fatal`
: Boolean flag, `true` if the error mode is fatal, read-only.

`TextDecoder.prototype.ignoreBOM`
: Boolean flag, `true` if the byte order marker is ignored, read-only.

`TextDecoder.prototype.decode(buffer, [options])`
: Returns a string with the text decoded from the `buffer` by `TextDecoder()`. The buffer can be `ArrayBuffer`. The `options` is a `TextDecodeOptions` dictionary with the property:
  

  `stream`
  : Boolean flag indicating if additional data will follow in subsequent calls to `decode()`: `true` if processing the data in chunks, and `false` for the final chunk or if the data is not chunked. By default is `false`.
  

  Example:
  

  ```javascript
  >> (new TextDecoder()).decode(new Uint8Array([206,177,206,178]))
  αβ
  ```



### TextEncoder

- `TextEncoder()`
- `TextEncoder.prototype.encode()`
- `TextEncoder.prototype.encodeInto()`

The `TextEncoder` object produces a byte stream with UTF-8 encoding from a stream of code points (0.4.3).

`TextEncoder()`
: Returns a newly constructed `TextEncoder` that will generate a byte stream with UTF-8 encoding.

`TextEncoder.prototype.encode(string)`
: Encodes `string` into a `Uint8Array` with UTF-8 encoded text.

`TextEncoder.prototype.encodeInto(string, uint8Array)`
: Encodes a `string` to UTF-8, puts the result into the destination `Uint8Array`, and returns a dictionary object that shows the progress of the encoding. The dictionary object contains two members:
  

  `read`
  : The number of UTF-16 units of code from the source `string` converted to UTF-8.
  

  `written`
  : The number of bytes modified in the destination `Uint8Array`.



## Timers

- `clearTimeout()`
- `setTimeout()`

`clearTimeout(timeout)`
: Cancels a `timeout` object created by `setTimeout()`.

`setTimeout(function, milliseconds[, argument1, argumentN])`
: Calls a `function` after a specified number of `milliseconds`. One or more optional `arguments` can be passed to the specified function. Returns a `timeout` object.
  

  Example:
  

  ```javascript
  function handler(v)
  {
      // ...
  }
  

  t = setTimeout(handler, 12);
  

  // ...
  

  clearTimeout(t);
  ```



### Global Functions

- `atob()`
- `btoa()`

`atob(encodedData)`
: Decodes a string of data which has been encoded using `Base64` encoding. The `encodedData` parameter is a binary string that contains Base64-encoded data. Returns a string that contains decoded data from `encodedData`.
  

  The similar `btoa()` method can be used to encode and transmit data which may otherwise cause communication problems, then transmit it and use the `atob()` method to decode the data again. For example, you can encode, transmit, and decode control characters such as ASCII values `0` through `31`.
  

  Example:
  

  ```javascript
  const encodedData = btoa("text to encode"); // encode a string
  const decodedData = atob(encodedData); // decode the string
  ```

`btoa(stringToEncode)`
: Creates a Base64-encoded ASCII string from a binary string. The `stringToEncode` parameter is a binary string to encode. Returns an ASCII string containing the Base64 representation of `stringToEncode`.
  

  The method can be used to encode data which may otherwise cause communication problems, transmit it, then use the `atob()` method to decode the data again. For example, you can encode control characters such as ASCII values `0` through `31`.
  

  Example:
  

  ```javascript
  const encodedData = btoa("text to encode"); // encode a string
  const decodedData = atob(encodedData); // decode the string
  ```



## Built-in Modules



### Buffer

The `Buffer` object is a Node.js-compatible way to work with binary data. Due to the file's extensive size, this section is limited to a comprehensive list of Buffer methods.

- `Buffer.alloc()`
- `Buffer.allocUnsafe()`
- `Buffer.byteLength()`
- `Buffer.compare()`
- `Buffer.concat()`
- `Buffer.from(array)`
- `Buffer.from(arrayBuffer)`
- `Buffer.from(buffer)`
- `Buffer.from(object)`
- `Buffer.from(string)`
- `Buffer.isBuffer()`
- `Buffer.isEncoding()`
- `buffer[]`
- `buf.buffer`
- `buf.byteOffset`
- `buf.compare()`
- `buf.copy()`
- `buf.equals()`
- `buf.fill()`
- `buf.includes()`
- `buf.indexOf()`
- `buf.lastIndexOf()`
- `buf.length`
- `buf.readIntBE()`
- `buf.readIntLE()`
- `buf.readUIntBE()`
- `buf.readUIntLE()`
- `buf.readDoubleBE()`
- `buf.readDoubleLE()`
- `buf.readFloatBE()`
- `buf.readFloatLE()`
- `buf.subarray()`
- `buf.slice()`
- `buf.swap16()`
- `buf.swap32()`
- `buf.swap64()`
- `buf.toJSON()`
- `buf.toString()`
- `buf.write()`
- `buf.writeIntBE()`
- `buf.writeIntLE()`
- `buf.writeUIntBE()`
- `buf.writeUIntLE()`
- `buf.writeDoubleBE()`
- `buf.writeDoubleLE()`
- `buf.writeFloatBE()`
- `buf.writeFloatLE()`

For detailed documentation of Buffer methods, please refer to [Node.js Buffer documentation](https://nodejs.org/api/buffer.html).



### Crypto

The Crypto module provides cryptographic functionality support. The Crypto module object is imported using `import crypto from 'crypto'`.

#### NOTE
Since 0.7.0, extended crypto API is available as a global [crypto](#njs-builtin-crypto) object.

- `crypto.createHash()`
- `crypto.createHmac()`

`crypto.createHash(algorithm)`
: Creates and returns a Hash object that can be used to generate hash digests using the given `algorithm`. The algorithm can be `md5`, `sha1`, and `sha256`.

`crypto.createHmac(algorithm, secret key)`
: Creates and returns an HMAC object that uses the given `algorithm` and `secret key`. The algorithm can be `md5`, `sha1`, and `sha256`.



#### Hash

- `hash.update()`
- `hash.digest()`

`hash.update(data)`
: Updates the hash content with the given `data`.

`hash.digest([encoding])`
: Calculates the digest of all of the data passed using `hash.update()`. The encoding can be `hex`, `base64`, and `base64url`. If encoding is not provided, a Buffer object is returned (0.4.4).
  

  #### NOTE
  Before version 0.4.4, a byte string was returned instead of a Buffer object.

`hash.copy()`
: Makes a copy of the current state of the hash (since 0.7.12).

Example:

```javascript
import crypto from 'crypto';

crypto.createHash('sha1').update('A').update('B').digest('base64url');
/* BtlFlCqiamG-GMPiK_GbvKjdK10 */
```



#### HMAC

- `hmac.update()`
- `hmac.digest()`

`hmac.update(data)`
: Updates the HMAC content with the given `data`.

`hmac.digest([encoding])`
: Calculates the HMAC digest of all of the data passed using `hmac.update()`. The encoding can be `hex`, `base64`, and `base64url`. If encoding is not provided, a Buffer object is returned (0.4.4).
  

  #### NOTE
  Before version 0.4.4, a byte string was returned instead of a Buffer object.



### fs

The `fs` module provides operations with the file system. The module object is imported using `import fs from 'fs'`.

- `fs.accessSync()`
- `fs.appendFileSync()`
- `fs.mkdirSync()`
- `fs.readdirSync()`
- `fs.readFileSync()`
- `fs.realpathSync()`
- `fs.renameSync()`
- `fs.rmdirSync()`
- `fs.symlinkSync()`
- `fs.unlinkSync()`
- `fs.writeFileSync()`
- `fs.promises.readFile()`
- `fs.promises.appendFile()`
- `fs.promises.writeFile()`
- `fs.promises.readdir()`
- `fs.promises.mkdir()`
- `fs.promises.rmdir()`
- `fs.promises.rename()`
- `fs.promises.unlink()`
- `fs.promises.symlink()`
- `fs.promises.access()`
- `fs.promises.realpath()`

For detailed documentation of fs methods, please refer to [Node.js fs documentation](https://nodejs.org/api/fs.html).



### Query String

The Query String module provides methods for parsing and formatting URL query strings. The module object is imported using `import qs from 'querystring'`.

- `querystring.decode()`
- `querystring.encode()`
- `querystring.escape()`
- `querystring.parse()`
- `querystring.stringify()`
- `querystring.unescape()`

`querystring.decode()`
: An alias to `querystring.parse()`.

`querystring.encode()`
: An alias to `querystring.stringify()`.

`querystring.escape(string)`
: Performs URL percent-encoding of the `string` in a manner optimized for the requirements of URL query strings. The method is used by `querystring.stringify()` and should not be used directly.

`querystring.parse(string[, separator[, equal[, options]]])`
: Parses the `string` as a URL query string and returns an object. The optional `separator` parameter (default: `&`) specifies the substring for delimiting key-value pairs. The optional `equal` parameter (default: `=`) specifies the substring for delimiting keys and values. The optional `options` parameter is an object that may contain the following property:
  

  `decodeURIComponent`
  : Function to use when decoding percent-encoded characters in the query string, default: `querystring.unescape()`.
  

  `maxKeys`
  : The maximum number of keys to parse, default: `1000`. The `0` value removes limitations for counting keys.
  

  Example:
  

  ```javascript
  >> qs.parse('foo=bar&abc=xyz&abc=123')
  {
      foo: 'bar',
      abc: ['xyz', '123']
  }
  ```

`querystring.stringify(object[, separator[, equal[, options]]])`
: Produces a URL query string from the `object` by iterating through its own properties. The optional `separator` parameter (default: `&`) specifies the substring for delimiting key-value pairs. The optional `equal` parameter (default: `=`) specifies the substring for delimiting keys and values. The optional `options` parameter is an object that may contain the following property:
  

  `encodeURIComponent`
  : Function to use when converting URL-unsafe characters to percent-encoding in the query string, default: `querystring.escape()`.
  

  Example:
  

  ```javascript
  >> qs.stringify({ foo: 'bar', baz: ['qux', 'quux'], corge: '' })
  'foo=bar&baz=qux&baz=quux&corge='
  ```

`querystring.unescape(string)`
: Performs decoding of URL percent-encoded characters in the `string`. The method is used by `querystring.parse()` and should not be used directly.



### XML

- `xml.parse()`
- `xml.c14n()`
- `xml.exclusiveC14n()`
- `xml.serialize()`
- `xml.serializeToString()`
- `XMLDoc`
- `XMLNode`
- `XMLAttr`

The XML module allows working with XML documents (since 0.7.10). The XML module object is imported using `import xml from 'xml'`.

Example:

```javascript
import xml from 'xml';

let data = `ToveJani`;
let doc = xml.parse(data);

console.log(doc.note.to.$text) /* 'Tove' */
console.log(doc.note.to.$attr$b) /* 'bar' */
console.log(doc.note.$tags[1].$text) /* 'Jani' */

let dec = new TextDecoder();
let c14n = dec.decode(xml.exclusiveC14n(doc.note));
console.log(c14n) /* 'ToveJani' */

c14n = dec.decode(xml.exclusiveC14n(doc.note.to));
console.log(c14n) /* 'Tove' */

c14n = dec.decode(xml.exclusiveC14n(doc.note, doc.note.to /* excluding 'to' */));
console.log(c14n) /* 'Jani' */
```

`parse(string | Buffer)`
: Parses a string or Buffer for an XML document; returns an `XMLDoc` wrapper object representing the parsed XML document.

`c14n(root_node[, excluding_node])`
: Canonicalizes `root_node` and its children according to [Canonical XML Version 1.1](https://www.w3.org/TR/xml-c14n). The `root_node` can be an `XMLNode` or `XMLDoc` wrapper object around XML structure. Returns a Buffer object that contains canonicalized output.
  

  `excluding_node`
  : Allows omitting from the output a part of the document.

`exclusiveC14n(root_node[, excluding_node[, withComments[,prefix_list]]])`
: Canonicalizes `root_node` and its children according to [Exclusive XML Canonicalization Version 1.0](https://www.w3.org/TR/xml-exc-c14n/).
  

  `root_node`
  : An `XMLNode` or `XMLDoc` wrapper object around XML structure.
  

  `excluding_node`
  : Allows omitting from the output a part of the document corresponding to the node and its children.
  

  `withComments`
  : A boolean value, `false` by default. If `true`, canonicalization corresponds to [Exclusive XML Canonicalization Version 1.0](http://www.w3.org/2001/10/xml-exc-c14n#WithComments). Returns a Buffer object that contains canonicalized output.
  

  `prefix_list`
  : An optional string with space-separated namespace prefixes for namespaces that should also be included in the output.

`serialize()`
: The same as `xml.c14n()` (since 0.7.11).

`serializeToString()`
: The same as `xml.c14n()` except it returns the result as a `string` (since 0.7.11).

`XMLDoc`
: An XMLDoc wrapper object around XML structure, the root node of the document.
  

  > `doc.$root`
  > : The document's root by its name or undefined.
  

  > `doc.abc`
  > : The first root tag named `abc` as an `XMLNode` wrapper object.

`XMLNode`
: An XMLNode wrapper object around an XML tag node.
  

  > `node.abc`
  > : The same as `node.$tag$abc`.
  

  > `node.$attr$abc`
  > : The node's attribute value of `abc`, writable since 0.7.11.
  

  > `node.$attr$abc=xyz`
  > : The same as `node.setAttribute('abc', xyz)` (since 0.7.11).
  

  > `node.$attrs`
  > : An `XMLAttr` wrapper object for all attributes of the node.
  

  > `node.$name`
  > : The name of the node.
  

  > `node.$ns`
  > : The namespace of the node.
  

  > `node.$parent`
  > : The parent node of the current node.
  

  > `node.$tag$abc`
  > : The first child tag of the node named `abc`, writable since 0.7.11.
  

  > `node.$tags`
  > : An array of all child tags.
  

  > `node.$tags = [node1, node2, ...]`
  > : The same as `node.removeChildren()`; `node.addChild(node1)`; `node.addChild(node2)` (since 0.7.11).
  

  > `node.$tags$abc`
  > : All child tags named `abc` of the node, writable since 0.7.11.
  

  > `node.$text`
  > : The content of the node, writable since 0.7.11.
  

  > `node.$text = 'abc'`
  > : The same as `node.setText('abc')` (since 0.7.11).
  

  > `node.addChild(nd)`
  > : Adds an XMLNode as a child to the node (since 0.7.11). `nd` is recursively copied before adding to the node.
  

  > `node.removeAllAttributes()`
  > : Removes all attributes of the node (since 0.7.11).
  

  > `node.removeAttribute(attr_name)`
  > : Removes the attribute named `attr_name` (since 0.7.11).
  

  > `node.removeChildren(tag_name)`
  > : Removes all child tags named `tag_name` (since 0.7.11). If `tag_name` is absent, all child tags are removed.
  

  > `node.removeText()`
  > : Removes the node's text value (0.7.11).
  

  > `node.setAttribute(attr_name, value)`
  > : Sets a value for `attr_name` (since 0.7.11). When the value is `null`, the attribute named `attr_name` is deleted.
  

  > `node.setText(value)`
  > : Sets a text value for the node (since 0.7.11). When the value is `null`, the text of the node is deleted.

`XMLAttr`
: An XMLAttrs wrapper object around XML node attributes.
  

  > `attr.abc`
  > : The attribute value of `abc`.



### zlib

The `zlib` module (0.5.2) provides compression and decompression functionality using zlib. The module object is imported using `import zlib from 'zlib'`.

- `zlib.constants`
- `zlib.deflateRawSync()`
- `zlib.deflateSync()`
- `zlib.inflateRawSync()`
- `zlib.inflateSync()`

`zlib.constants`
: Returns a dictionary of zlib constants.

`zlib.deflateRawSync(data[, options])`
: Compresses `data` using the Deflate algorithm without the zlib header.

`zlib.deflateSync(data[, options])`
: Compresses `data` using the Deflate algorithm.

`zlib.inflateRawSync(data[, options])`
: Decompresses `data` using the Deflate algorithm without the zlib header.

`zlib.inflateSync(data[, options])`
: Decompresses `data` using the Deflate algorithm.

The `options` parameter is an object that may contain the following properties:

`level`
: Compression level (default: `zlib.constants.Z_DEFAULT_COMPRESSION`).

`memLevel`
: Specifies how much memory should be allocated for the compression state (default: `zlib.constants.Z_DEFAULT_MEMLEVEL`).

`strategy`
: Tunes the compression algorithm (default: `zlib.constants.Z_DEFAULT_STRATEGY`).

`windowBits`
: Sets the window size (default: `zlib.constants.Z_DEFAULT_WINDOWBITS`).

`dictionary`
: Buffer containing the predefined compression dictionary.

`info`
: A boolean value, if `true`, returns an object with buffer and engine.

`chunkSize`
: Chunk size for compression (default: `zlib.constants.Z_DEFAULT_CHUNK`).

Example:

```javascript
import zlib from 'zlib';

const deflated = zlib.deflateSync('Hello World!');
const inflated = zlib.inflateSync(deflated);

console.log(inflated.toString()); // 'Hello World!'
```


# https://en.angie.software/angie/docs/configuration/quickaccess.md





# Quick Access to Angie Directives and Variables

You can quickly access documentation for all Angie directives and variables
without searching the site via our short link service at [https://angie.ws/en/](https://angie.ws/en/).
It enables shortcuts to frequently used directives, variables and topics.



## HTTP and Core Directives

Directives in the [Core](https://en.angie.software//angie/docs/configuration/modules/core.md#core) and [HTTP](https://en.angie.software//angie/docs/configuration/modules/index.md#modules-http) modules
use the `/h/` prefix (short for `http`).

Examples:

- [listen](https://en.angie.software//angie/docs/configuration/modules/http/index.md#listen): [https://angie.ws/en/h/listen](https://angie.ws/en/h/listen)
- [server](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server): [https://angie.ws/en/h/server](https://angie.ws/en/h/server)
- [worker_connections](https://en.angie.software//angie/docs/configuration/modules/core.md#worker-connections): [https://angie.ws/en/h/worker_connections](https://angie.ws/en/h/worker_connections)

And so on.

#### NOTE
The [server](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server) directive from the HTTP [Upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream) module
is available at: [https://angie.ws/en/hu/server](https://angie.ws/en/hu/server).



### Upstream Directives

Directives in the HTTP [Upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream) module
use the `/hu/` prefix (short for `http upstream`). Examples:

- [keepalive_requests](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive-requests): [https://angie.ws/en/hu/keepalive_requests](https://angie.ws/en/hu/keepalive_requests)
- [keepalive_time](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive-time): [https://angie.ws/en/hu/keepalive_time](https://angie.ws/en/hu/keepalive_time)
- [keepalive_timeout](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive-timeout): [https://angie.ws/en/hu/keepalive_timeout](https://angie.ws/en/hu/keepalive_timeout)

And so on.



## Stream Module Directives

Directives in the [Stream](https://en.angie.software//angie/docs/configuration/modules/index.md#modules-stream) modules use the `/s/` prefix
(short for `stream`):

- [listen](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#s-listen): [https://angie.ws/en/s/listen](https://angie.ws/en/s/listen)
- [map](https://en.angie.software//angie/docs/configuration/modules/stream/stream_map.md#s-map): [https://angie.ws/en/s/map](https://angie.ws/en/s/map)
- [server](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#s-server): [https://angie.ws/en/s/server](https://angie.ws/en/s/server)

And so on.

#### NOTE
The [server](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#s-server) directive from the Stream [Upstream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#stream-upstream) module
is available at: [https://angie.ws/en/su/server](https://angie.ws/en/su/server).



### Upstream Directives

Directives in the Stream [Upstream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#stream-upstream) module
use the `/su/` prefix (short for `stream upstream`):

- [upstream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-upstream): [https://angie.ws/en/su/upstream](https://angie.ws/en/su/upstream)
- [server](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server): [https://angie.ws/en/su/server](https://angie.ws/en/su/server)
- [state (PRO)](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-state): [https://angie.ws/en/su/state](https://angie.ws/en/su/state)

And so on.



## Variables

Variables use the same prefix scheme.

HTTP variables (`/h/` prefix):

- [$angie_version](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-angie-version): [https://angie.ws/en/h/$angie_version](https://angie.ws/en/h/$angie_version)
- [$upstream_status](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-status): [https://angie.ws/en/h/$upstream_status](https://angie.ws/en/h/$upstream_status)

Stream variables (`/s/` prefix):

- [$angie_version](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#v-s-angie-version): [https://angie.ws/en/s/$angie_version](https://angie.ws/en/s/$angie_version)
- [$upstream_session_time](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#v-s-upstream-session-time): [https://angie.ws/en/s/$upstream_session_time](https://angie.ws/en/s/$upstream_session_time)

For placeholder variables
such as `$http_` or `$cookie_`,
use the prefix up to the underscore: [https://angie.ws/en/h/$http](https://angie.ws/en/h/$http).



## Additional Topics

Short links are also available for other topics:

- [Certificate Chaining](https://angie.ws/en/certificate_chaining)
- [Combined Locations](https://angie.ws/en/combined_locations)
- [Compact Server](https://angie.ws/en/compact_server)
- [Configuration](https://angie.ws/en/configure)
- [Configuration File Reloading](https://angie.ws/en/configfile_reloading)
- [Configuration Hashes](https://angie.ws/en/configure_hashes)
- [Control Configuration Changes](https://angie.ws/en/control_config_change)
- [Control Signals](https://angie.ws/en/control_signals)
- [Cyclic Memory Buffer](https://angie.ws/en/cyclic_memory_buffer)
- [Debug Logging](https://angie.ws/en/debug_logging)
- [Dummy Server](https://angie.ws/en/dummy_server)
- [HTTPS Configuration](https://angie.ws/en/https_configuration)
- [HTTPS Optimization](https://angie.ws/en/https_optimization)
- [HTTPS with Separate IPs](https://angie.ws/en/https_separate_ips)
- [HTTP Sessions](https://angie.ws/en/http_sessions)
- [Inheritance](https://angie.ws/en/inheritance)
- [Load Balancing](https://angie.ws/en/load_balancing)
- [Location Redirect](https://angie.ws/en/location_redirect)
- [Log Rotation](https://angie.ws/en/log_rotation)
- [Method Usage](https://angie.ws/en/methods_use)
- [Named Locations](https://angie.ws/en/named_location)
- [Paths](https://angie.ws/en/paths)
- [Picking a Location](https://angie.ws/en/pick_location)
- [Proxy Pass URI](https://angie.ws/en/proxy_pass_uri)
- [Proxying](https://angie.ws/en/proxying)
- [Request Processing](https://angie.ws/en/request_processing)
- [Runtime CLI Options](https://angie.ws/en/runtime_cli_options)
- [Service Upgrade](https://angie.ws/en/service_upgrade)
- [SNI (Server Name Indication)](https://angie.ws/en/sni)
- [Source Build Features](https://angie.ws/en/sourcebuild_features)
- [SSL Error Codes](https://angie.ws/en/ssl_error_codes)
- [Stream Sessions](https://angie.ws/en/stream_sessions)
- [Syntax](https://angie.ws/en/syntax)
- [Syslog Logging](https://angie.ws/en/syslog_logging)
- [Virtual Server Selection](https://angie.ws/en/virtual_server_selection)
- [WebSocket Proxying](https://angie.ws/en/websocket_proxy)


# https://en.angie.software/angie/docs/configuration/acme.md








# ACME Configuration

The [ACME](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme) module in Angie enables automatic certificate
retrieval using the [ACME protocol](https://datatracker.ietf.org/doc/html/rfc8555). The ACME protocol supports
various domain verification methods (also called "validation"); this module
implements [HTTP validation](#acme-config-http), [DNS validation](#acme-config-dns), [ALPN validation](#acme-config-alpn), and
[hook-based validation](#acme-config-hooks)
through a custom external service.



## Configuration Steps

General steps to enable certificate requests in the configuration:

- **Configure an ACME client** in the `http` block using the
  [acme_client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) directive, which specifies a unique client name and other
  parameters. Multiple ACME clients can be configured.
- **Specify the domains for which certificates are requested**: A single
  certificate will be issued for all domain names listed in [server_name](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server-name)
  directives within all `server` blocks that use [acme](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#id1) directives
  pointing to the same ACME client.

  IP addresses (IPv4 or IPv6) specified in [server_name](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server-name) are also valid
  certificate identifiers, except with [DNS validation](#acme-config-dns).

  Note that public certificate authorities may issue certificates for IP
  addresses only under specific certificate profiles; for example, Let's
  Encrypt currently requires a profile that permits IP identifiers (see its
  [profiles documentation](https://letsencrypt.org/docs/profiles/)).
  To request one, set the `profile=` parameter of [acme_client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client).
- **Set up request handling and ACME callbacks**: This is required to verify
  domain ownership. The setup depends on the chosen domain validation method:

  | Method                                | User Requirements                                                                                                                                                                                                                                                                                       | Multi-domain   | Wildcard Domains   |
  |---------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------|--------------------|
  | [HTTP Validation](#acme-config-http)  | Open port 80 (or the one specified in [acme_http_port](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-http-port))
for incoming connections on the Angie server.                                                                                                 | ✔              |                    |
  | [DNS Validation](#acme-config-dns)    | Open port 53 (or the one specified in [acme_dns_port](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-dns-port))
for incoming connections on the Angie server.

Set an NS record for the `_acme-challenge.` subdomain
pointing to your Angie server. | ✔              | ✔                  |
  | [ALPN Validation](#acme-config-alpn)  | Open port 443 (or the TLS port used by your server)
for incoming connections on the Angie server.                                                                                                                                                                                                   | ✔              |                    |
  | [Hook validation](#acme-config-hooks) | Create an external service (script or application)
that can, on request from Angie, update DNS records
or serve a special response via the web server.                                                                                                                                          | ✔              | ✔                  |
- **Configure SSL using the obtained certificate and key**: The module makes
  certificates and keys available as [embedded variables](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme-variables)
  that can be used in [configuration](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) to populate
  [ssl_certificate](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-certificate) and [ssl_certificate_key](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-certificate-key).

  For SSL setup instructions, refer to [SSL Configuration](https://en.angie.software//angie/docs/configuration/ssl.md#ssl-config).



## Implementation Details

Client keys and certificates are stored in [PEM encoding](https://datatracker.ietf.org/doc/html/rfc7468) within subdirectories of the
directory specified by the `--http-acme-client-path` [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure):

```console
$ ls /var/lib/angie/acme/example/

  account.key  certificate.pem  private.key
```

#### NOTE
These files persist on disk between restarts. On startup, the client reuses
a stored certificate that is still valid instead of requesting a new one,
avoiding both the issuance delay and unnecessary requests to the CA, which
may be subject to [rate limits](https://letsencrypt.org/docs/rate-limits/). In a container, place the
storage directory (by default `/var/lib/angie/acme/`) on a persistent
volume so that issued certificates survive container recreation; see
[running Angie in a container](https://en.angie.software//angie/docs/installation/docker.md#running).

#### NOTE
Reloading the configuration (`angie -s reload`) re-evaluates every ACME
client against the certificates stored on disk. A client whose certificate is
not currently valid (including one whose previous request ended in an error)
is requested again immediately, regardless of [retry_after_error](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client). The retry delay (and `retry_after_error=off`) applies only
while Angie keeps running; it does not survive a reload. Reloading repeatedly
while a request keeps failing can therefore send frequent requests to the CA,
subject to the rate limits noted above.

The ACME client requires an account on the CA server. To create and manage this
account, the client uses a private key (`account.key`). If no key exists,
it is generated at startup. The client then uses this key to register the
account with the server.

#### NOTE
If you already have an account key, place it in the client's subdirectory
before starting to reuse the account. Alternatively, specify the key file
using the `account_key` parameter in [acme_client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client).

Some CAs require the ACME account to be linked with an existing external account
through [External Account Binding](https://datatracker.ietf.org/doc/html/rfc8555#section-7.3.4) (EAB) before
they will issue certificates. To enable this, configure the `eab`
parameter of [acme_client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) with the key identifier and MAC key the CA
provides; see the directive's description for the exact syntax.

The ACME client also uses a separate key (`private.key`) for Certificate
Signing Requests (CSRs). This certificate key is automatically created at
startup if needed.

At startup, the client requests a certificate if one doesn't exist, signing and
sending a CSR for all domains under its management to the CA server. The server
verifies domain ownership using [HTTP](#acme-config-http) or [DNS
validation](#acme-config-dns) and issues a certificate, which the client saves
locally (`certificate.pem`).

As mentioned earlier, a single certificate covers all domain names managed by
the same ACME client, potentially resulting in a multi-domain certificate. The
list of all names covered by the certificate can be found in the Subject
Alternative Name (SAN) section of the obtained certificate. To check this from
the command line:

```console
$ openssl x509 -in certificate.pem -noout -text | grep -A5 "Subject Alternative Name"
```

When a certificate is about to expire or the domain list changes, the client
signs and sends another CSR to the CA server. The server re-verifies ownership
and issues a new certificate, which the client installs locally, replacing the
previous one.

In the [configuration](https://en.angie.software//angie/docs/configuration/configfile.md#configfile), the obtained certificate and its
corresponding key are available through the prefix variables
[$acme_cert_](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-cert-name) and [$acme_cert_key_](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-cert-key-name). Their values are the
contents of the respective files, which should be used with the
[ssl_certificate](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-certificate) and [ssl_certificate_key](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-certificate-key) directives:

```nginx
server {

    listen 443 ssl;

    server_name example.com www.example.com;
    acme example;

    ssl_certificate $acme_cert_example;
    ssl_certificate_key $acme_cert_key_example;
}
```

#### NOTE
The ACME client resolves the CA server's host name through the configured
[resolver](https://en.angie.software//angie/docs/configuration/modules/http/index.md#resolver), which must be present in the same context. On a host
without IPv6 connectivity, the resolver may still issue AAAA (IPv6) queries
for the CA and fail to connect; disable them with the `ipv6=off`
parameter, for example `resolver 127.0.0.53 ipv6=off;`.



## Domain Collection vs. Certificate Usage

The [acme](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#id1) directive serves only to collect domain names
for certificate requests.
It does not control where the certificate can be used:
any `server` block can reference the obtained certificate
through the [$acme_cert_](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-cert-name) variable,
regardless of whether the block contains an `acme` directive.

For example, if you have a wildcard server block
that already covers all subdomains,
additional server blocks for specific subdomains
do not need the `acme` directive:

```nginx
http {

    resolver 127.0.0.53;

    acme_client example https://acme-v02.api.letsencrypt.org/directory
        challenge=dns;

    # This block lists the domains for the certificate request
    server {

        listen 443 ssl;

        server_name example.com *.example.com;
        acme example;

        ssl_certificate $acme_cert_example;
        ssl_certificate_key $acme_cert_key_example;
    }

    # This block uses the same certificate but does not
    # add its server_name to the certificate request
    server {

        listen 443 ssl;

        server_name app.example.com;

        ssl_certificate $acme_cert_example;
        ssl_certificate_key $acme_cert_key_example;
    }
}
```



### Explicit Domain List

To control the exact set of domain names in a certificate
without relying on automatic collection from all server blocks,
create a dedicated `server` block
that contains only the [server_name](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server-name) and [acme](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#id1) directives.
To prevent this block from handling real traffic,
bind it to a Unix domain socket:

```nginx
# Dedicated block that defines the certificate's domain list
server {

    listen unix:/tmp/acme_example.sock;

    server_name example.com www.example.com;
    acme example;
}
```

Other `server` blocks can then use the certificate
through the [$acme_cert_](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-cert-name) variable
without affecting which domains are requested.



### Separate Certificates for Different Domains

Each [acme_client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) manages a single certificate. To obtain several
independent certificates (for example, for unrelated domains that should not
share one certificate), configure a separate [acme_client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) for each in the
`http` block, and point the [acme](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#id1) directive of every `server`
block at the relevant client by name:

```nginx
http {

    resolver 127.0.0.53;

    # Two independent clients, each managing its own certificate
    acme_client shop https://acme-v02.api.letsencrypt.org/directory
        challenge=http;

    acme_client blog https://acme-v02.api.letsencrypt.org/directory
        challenge=http;

    server {

        listen 443 ssl;

        server_name shop.example.com www.shop.example.com;
        acme shop;

        ssl_certificate $acme_cert_shop;
        ssl_certificate_key $acme_cert_key_shop;
    }

    server {

        listen 443 ssl;

        server_name blog.example.com;
        acme blog;

        ssl_certificate $acme_cert_blog;
        ssl_certificate_key $acme_cert_key_blog;
    }
}
```



## HTTP Validation

Validation is handled automatically. The process involves the ACME server, upon
receiving a request, [retrieving a special token file via HTTP](https://datatracker.ietf.org/doc/html/rfc8555#section-8.3) from the client
at the address `/.well-known/acme-challenge/`. Our ACME module
tracks and processes such requests automatically. When the expected response
with the correct content is received, the ACME server confirms that the domain
belongs to the client.



### Configuration Example

In this example, the ACME client named `example` manages certificates for
`example.com` and `www.example.com` (note that wildcard certificates
aren't supported with HTTP validation):

```nginx
http {

    resolver 127.0.0.53; # Required for the 'acme_client' directive

    acme_client example https://acme-v02.api.letsencrypt.org/directory;

    server {

        listen 80; # Optional if no server listens on the HTTP challenge port
                   # (see 'acme_http_port' directive)

        listen 443 ssl;

        server_name example.com www.example.com;
        acme example;

        ssl_certificate $acme_cert_example;
        ssl_certificate_key $acme_cert_key_example;
    }
}
```

As noted earlier, port 80 must be open to handle HTTP ACME calls.
If no server is configured to listen on the HTTP challenge port,
the module creates a dedicated listener on port 80 (or the one set in
[acme_http_port](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-http-port)). A separate [server](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server) block is not required.



## DNS Validation

Validation is handled automatically. When processing a certificate request, the
ACME server performs a [special DNS query](https://datatracker.ietf.org/doc/html/rfc8555#section-8.4) to the
`_acme-challenge.` subdomain of the domain being verified. Once the
expected response is received, the ACME server confirms that the domain belongs
to the client.

Our ACME module tracks and processes such requests automatically, provided that
your DNS records are configured properly to designate the Angie server as the
authoritative name server for the `_acme-challenge.` subdomain. Configure
the TXT response TTL with [acme_dns_ttl](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-dns-ttl).

DNS validation proves control of a domain name, so it cannot validate IP
address identifiers: an IP address in [server_name](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server-name) is skipped for a
client configured with `challenge=dns`.
Each such `server` block must still list at least one domain name
that the client can validate.

#### NOTE
The Angie server must be reachable from the internet
on UDP port 53 (or the one specified in [acme_dns_port](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-dns-port)).
If the server is behind a firewall,
make sure this port is open for incoming connections.

For example, to verify the domain `example.com` using an Angie server at
IP address `203.0.113.10`, your domain's DNS configuration should include
the following records:

```none
_acme-challenge.example.com. 60    IN      NS       ns.example.com.
             ns.example.com. 60    IN       A       203.0.113.10
```

This configuration delegates DNS resolution for
`_acme-challenge.example.com` to `ns.example.com`, ensuring
`ns.example.com` is accessible by mapping it to the IP address
(`203.0.113.10`).

#### WARNING
NS record propagation can take anywhere from a few minutes to 48 hours
depending on TTL and DNS provider. It is recommended to verify the
configuration is correct before requesting a certificate.

To verify that DNS is configured correctly, you can use the following commands:

```console
$ dig NS _acme-challenge.example.com +short  # Check NS record for _acme-challenge subdomain

  ns.example.com.

$ dig A ns.example.com +short  # Check A record for name server

  203.0.113.10

$ nc -zv 203.0.113.10 53  # Check DNS server accessibility on port 53
```

This method allows requesting wildcard certificates, for example, a certificate
that includes the entry `*.example.com` in the Subject Alternative Name
(SAN) section. To explicitly request a certificate for a subdomain, such as
`www.example.com`, you must separately verify that subdomain using the
method described above.

#### WARNING
The applicability of this scenario largely depends on the capabilities
provided by your DNS provider; some providers do not allow such
configurations.



### Configuration Example

Overall, the configuration is similar to the example in the previous section.
There is no need for HTTP-specific settings; instead, it's sufficient to set
`challenge=dns` for the [acme_client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) directive.

In this example, the ACME client named `example` manages certificates for
`example.com` and `*.example.com`:

```nginx
http {

    resolver 127.0.0.53;

    acme_client example https://acme-v02.api.letsencrypt.org/directory
        challenge=dns;

    server {

        server_name example.com *.example.com;
        acme example;

        ssl_certificate $acme_cert_example;
        ssl_certificate_key $acme_cert_key_example;
    }
}
```



## ALPN Validation

Validation is handled automatically. The ACME server connects using TLS and
requests the `acme-tls/1` protocol via ALPN. The module serves a temporary
certificate for the validation request.

To enable this method, configure `challenge=alpn` in the
[acme_client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) directive and ensure your TLS listener is reachable on
port 443 (or the port used for TLS).



### Configuration Example

The configuration is similar to the previous sections; it is enough to set
`challenge=alpn` for the [acme_client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) directive and ensure the TLS
server is reachable on port 443.

In this example, the ACME client named `example` manages a certificate
for `example.com` and `www.example.com`:

```nginx
http {

    resolver 127.0.0.53;

    acme_client example https://acme-v02.api.letsencrypt.org/directory
        challenge=alpn;

    server {

        listen 443 ssl;

        server_name example.com www.example.com;
        acme example;

        ssl_certificate $acme_cert_example;
        ssl_certificate_key $acme_cert_key_example;
    }
}
```



## Hook-Based Validation

Unlike the previous methods, this validation requires additional effort. The
ACME server performs standard [HTTP validation](#acme-config-http) or
[DNS validation](#acme-config-dns), but instead of interacting directly
with the Angie server, it communicates with an external service managed by the
Angie server using hook calls ([acme_hook](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-hook)). This service configures a
separate DNS or HTTP server where the ACME server sends its requests.

Once the ACME server receives the expected response from the configured DNS or
HTTP server, it confirms domain ownership.

When certificate issuance or renewal requires domain verification,
Angie generates an internal request
to the named `location` containing the [acme_hook](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-hook) directive.
How this request is handled depends entirely on the other directives
configured in the same `location`.

The general pattern is:

1. Create a named `location` with the [acme_hook](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-hook) directive.
2. Configure a request handler in the same `location`
   using whatever module fits your setup:
   [fastcgi_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-pass) for FastCGI,
   [proxy_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass) for HTTP,
   `cgi` for CGI scripts, etc.
3. Pass ACME [variables](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme-variables)
   to the handler using the mechanism it supports,
   for example `fastcgi_param` for FastCGI
   or `cgi_set_var` for CGI.

The handler must return a `2xx` status code,
which can be sent via the `Status` header.
Any other code is treated as an error,
and certificate renewal is halted.
Output from the handler is ignored.



### Minimal Configuration

Regardless of the handler used,
the hook `location` follows this structure:

```nginx
location @acme_hook_location {

    acme_hook example;

    # Handler directive (fastcgi_pass, proxy_pass, cgi on, ...)
    # Pass ACME variables using the handler's mechanism:
    #   ACME_HOOK       — $acme_hook_name ("add" or "remove")
    #   ACME_CHALLENGE  — $acme_hook_challenge ("dns" or "http")
    #   ACME_DOMAIN     — $acme_hook_domain
    #   ACME_TOKEN      — $acme_hook_token
    #   ACME_KEYAUTH    — $acme_hook_keyauth
}
```

For DNS validation, the handler must use `ACME_HOOK`
to determine the action:
when it is `add`,
create a TXT record for `_acme-challenge.*ACME_DOMAIN*`
with the value from `ACME_KEYAUTH`;
when it is `remove`, delete that record.



### FastCGI Example

In this example, the ACME client `example` is configured for domain
verification using DNS callbacks, indicated by the `challenge=dns`
parameter in the [acme_client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) directive.

The `server` block applies to all subdomains of `example.com` (e.g.,
`*.example.com`) and uses the ACME client `example` to manage
certificates, as specified by the [acme](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#id1) directive.

A named `location` block handles the hook calls.
The [acme_hook](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-hook) directive associates it
with the ACME client `example`.
Hook requests are sent to a local FastCGI server
on port 9000 using [fastcgi_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-pass).
The `fastcgi_param` directives pass
the ACME variables to the external service.

```nginx
acme_client example https://acme-v02.api.letsencrypt.org/directory
    challenge=dns;

server {

    listen 80;

    server_name *.example.com;

    acme example;

    ssl_certificate $acme_cert_example;
    ssl_certificate_key $acme_cert_key_example;

    location @acme_hook_location {

        acme_hook example;

        fastcgi_pass localhost:9000;

        fastcgi_param ACME_CLIENT $acme_hook_client;
        fastcgi_param ACME_HOOK $acme_hook_name;
        fastcgi_param ACME_CHALLENGE $acme_hook_challenge;
        fastcgi_param ACME_DOMAIN $acme_hook_domain;
        fastcgi_param ACME_TOKEN $acme_hook_token;
        fastcgi_param ACME_KEYAUTH $acme_hook_keyauth;

        include fastcgi.conf;
    }
}
```

The following Perl script demonstrates a corresponding external FastCGI service:

```perl
#!/usr/bin/perl

use strict; use warnings;

use FCGI;

my $socket = FCGI::OpenSocket(":9000", 5);
my $request = FCGI::Request(\*STDIN, \*STDOUT, \*STDERR, \%ENV, $socket);

while ($request->Accept() >= 0) {
    print "\r\n";

    my $client =    $ENV{ACME_CLIENT};
    my $hook =      $ENV{ACME_HOOK};
    my $challenge = $ENV{ACME_CHALLENGE};
    my $domain =    $ENV{ACME_DOMAIN};
    my $token =     $ENV{ACME_TOKEN};
    my $keyauth =   $ENV{ACME_KEYAUTH};

    if ($hook eq 'add') {

        DNS_set_TXT_record("_acme-challenge.$domain.", $keyauth);

    } elsif ($hook eq 'remove') {

        DNS_clear_TXT_record("_acme-challenge.$domain.");
    }
};

FCGI::CloseSocket($socket);
```

Here, `DNS_set_TXT_record()` and `DNS_clear_TXT_record()` are
functions assumed to add and remove TXT records in the configuration of an
external DNS server that the ACME server queries. These records must contain the
data provided by the Angie server to allow the external DNS server to
successfully pass validation, similar to the process described in
[DNS Validation](#acme-config-dns). The implementation details of such functions are beyond
the scope of this guide; for example, parameters can also be passed through the
request URI:

```nginx
# ...

location @acme_hook_location {

    acme_hook example uri=/acme_hook/$acme_hook_name?domain=$acme_hook_domain&key=$acme_hook_keyauth;

    fastcgi_pass localhost:9000;

    fastcgi_param REQUEST_URI $request_uri;
    fastcgi_param ACME_CLIENT $acme_hook_client;
    fastcgi_param ACME_CHALLENGE $acme_hook_challenge;
    fastcgi_param ACME_TOKEN $acme_hook_token;

    include fastcgi.conf;
}
```

### PHP-FPM Example

Another example, using PHP-FPM:

```nginx
location @acme_hook_location {

    acme_hook example;
    root /var/www/dns;
    fastcgi_pass unix:/run/php-fpm/php-dns.sock;
    fastcgi_index hook.php;
    fastcgi_param SCRIPT_FILENAME /var/www/dns/hook.php;
    include fastcgi_params;

    fastcgi_param ACME_CLIENT $acme_hook_client;
    fastcgi_param ACME_HOOK $acme_hook_name;
    fastcgi_param ACME_CHALLENGE $acme_hook_challenge;
    fastcgi_param ACME_DOMAIN $acme_hook_domain;
    fastcgi_param ACME_TOKEN $acme_hook_token;
    fastcgi_param ACME_KEYAUTH $acme_hook_keyauth;
}
```

```ini
[dns]
listen = /run/php-fpm/php-dns.sock
listen.mode = 0666
user = angie
group = angie
chdir = /var/www/dns
# ...
```

Parameters passed can be accessed in PHP via `$_SERVER['...']`.



## ACME in the Stream Module

The Stream [ACME](https://en.angie.software//angie/docs/configuration/modules/stream/stream_acme.md#stream-acme) module enables automated
certificate issuance and usage for TCP traffic.
For it to work correctly, you must first configure its HTTP counterpart:
the ACME client must be declared in the `http` context,
and the `stream` block itself must be placed *after* the `http` block
in the configuration.



### Configuration Example

By default, HTTP validation mode is used to obtain certificates.
As mentioned in the [HTTP Validation](#acme-config-http) section,
this requires an HTTP server listening on port 80:

```nginx
# HTTP part
http {

    resolver 127.0.0.53;

    # ACME client for the stream part
    acme_client example https://acme-v02.api.letsencrypt.org/directory;

    # Server for HTTP validation
    server {

        listen 80;
        return 444;
    }
}

# Stream part
stream {

    server {

        listen 12345 ssl;
        proxy_pass backend_upstream;

        ssl_certificate $acme_cert_example;
        ssl_certificate_key $acme_cert_key_example;

        server_name example.com www.example.com;
        acme example; # reference to the ACME client defined in the HTTP part
    }

    upstream backend_upstream {

        server 127.0.0.1:54321;
    }
}
```

You can also use DNS validation
by configuring `challenge=dns` in the [acme_client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) directive;
in that case, the server will not be needed.



## Migrating from **certbot**

If you previously used [certbot](https://certbot.eff.org/)
to obtain and renew SSL certificates from Let's Encrypt
before [migrating from nginx to Angie](https://en.angie.software//angie/docs/configuration/migration.md#migration),
follow these steps to transition to using our ACME module.

Suppose you configured certificates as follows:

```console
$ sudo certbot --nginx -d example.com -d www.example.com
```

The configuration automatically created by this command
is typically located in `/etc/nginx/sites-available/example.conf`
and looks something like this:

```nginx
server {

    listen 80;
    server_name example.com www.example.com;
    return 301 https://$host$request_uri;
}

server {

    listen 443 ssl;
    server_name example.com www.example.com;

    root /var/www/example;
    index index.html;

    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
}
```

In the example above, the highlighted lines need to be modified.
Depending on your circumstances and preferences, configure
[HTTP validation](#acme-config-http)
or [DNS validation](#acme-config-dns) using the ACME module.

The resulting [Angie configuration](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)
might look something like this:

```nginx
http {

    resolver 127.0.0.53;

    acme_client example https://acme-v02.api.letsencrypt.org/directory;

    server {

        listen 80;
        server_name example.com www.example.com;
        return 301 https://$host$request_uri;
    }

    server {
        listen 443 ssl;
        server_name example.com www.example.com;

        root /var/www/example;
        index index.html;

        acme                 example;

        ssl_certificate      $acme_cert_example;
        ssl_certificate_key  $acme_cert_key_example;
    }
}
```

Remember to reload the configuration
[after making changes](https://en.angie.software//angie/docs/configuration/runtime.md#control-config-change):

```console
$ sudo kill -HUP $(cat /run/angie.pid)
```

Once you have verified that this configuration works,
you can delete the **certbot** certificates
and disable or remove certbot entirely from the server
if it is no longer used elsewhere,
for example:

```console
$ sudo rm -rf /etc/letsencrypt

$ sudo systemctl stop certbot.timer
$ sudo systemctl disable certbot.timer
$ # -- or --
$ sudo rm /etc/cron.d/certbot

$ sudo apt remove certbot
$ # -- or --
$ sudo dnf remove certbot
```


# https://en.angie.software/angie/docs/configuration/cluster.md





# Angie Cluster Setup

This guide describes the process of creating a fault-tolerant Angie cluster
with automatic configuration synchronization
and virtual IP address failover.



## Preparing Cluster Nodes for Synchronization

The first step is to prepare all cluster nodes
by configuring user accounts
and ensuring secure access between servers.



### Configuring Users and Access Permissions

Create a user on all nodes
(for example, `angie-ha-sync`) with `sudo` privileges:

```console
$ sudo adduser angie-ha-sync
```

Set a password if necessary:

```console
$ sudo passwd angie-ha-sync
```

#### NOTE
In some operating systems (for example, ALT Linux),
you should add the user to the `wheel` group:

```console
$ sudo usermod -a -G wheel angie-ha-sync
```

To work with `rsync` when MAC is enabled in Astra Linux, set
the correct integrity level:

```console
$ sudo pdpl-user -i 63 angie-ha-sync
```

Configure sudo without password:

```console
$ echo "angie-ha-sync ALL=(ALL:ALL) NOPASSWD:ALL" | sudo tee -a /etc/sudoers
```

On the master node, create SSH keys and copy them to backup nodes:

```console
$ su - angie-ha-sync
$ ssh-keygen -t rsa
$ ssh-copy-id angie-ha-sync@node2_hostname
```

#### WARNING
Before copying SSH keys, ensure that the
`/etc/ssh/sshd_config` file has the option:

`PasswordAuthentication yes`

After setting up key-based access, set the value to `no` to improve
security.

#### NOTE
For cross-synchronization of Angie configuration, copy the user keys
to all nodes:

```console
$ scp -p ~angie-ha-sync/.ssh/id_rsa angie-ha-sync@node2_hostname:.ssh/
```



## Installing Angie and angie-ha-sync

After preparing the nodes, you need to install the main cluster components:
Angie and the configuration synchronization package.

Configure the repository on all nodes according to the instructions for your system packages:

- [Instructions for Angie](https://en.angie.software//angie/docs/installation/oss_packages.md#oss-packages)
- [Instructions for Angie PRO](https://en.angie.software//angie/docs/installation/pro_packages.md#pro-packages)



### Installing angie-ha-sync

The configuration synchronization module is available in the following packages:

- Angie: `angie-ha-sync`
- Angie PRO: `angie-pro-ha-sync`

#### NOTE
When installing this package on a clean system,
the corresponding `angie` or `angie-pro` package
will also be installed as a dependency.

On all nodes, install the package using your OS package manager, for example:

```console
$ sudo {apk|apt|pkg|yum|zypper} {add|install} angie-pro-ha-sync
```



## Configuring Configuration Synchronization

The next step is setting up automatic synchronization of configuration files
between cluster nodes.

#### NOTE
Synchronization principles:

- Synchronization is performed via `rsync`.
- Only occurs when the Angie service is running.
- Executed manually (command `angiehasync -Sd`).
- Works in one direction: from master node to backup.
- `rsync` runs in daemon mode.



### Configuring `rsync`

Create an `rsync` configuration (`/etc/rsyncd.conf`) on the nodes:

```ini
[angie] # Directory with Angie configuration
    path = /etc/angie
# User for synchronization
    uid = angie-ha-sync
# User group
    gid = angie-ha-sync
# IP or subnet from which connections are allowed
    hosts allow = 10.21.8.0/24
# Deny all others
    hosts deny = *
```

Depending on the OS, start the daemon:

```console
$ sudo service rsyncd start # or $ sudo service rsync start
```

#### NOTE
For some systems, there are ready-made instructions:

- [ALT](https://www.altlinux.org/Настройка_rsync-сервера)
- [Astra](https://wiki.astralinux.ru/pages/viewpage.action?pageId=41191598#id-Архивированиеивосстановлениефайловссохранениеммандатныхатрибутов-RSYNC)



### Configuring the Synchronization File

Edit `/etc/angiehasync/angiehasync.conf`:

```ini
M_NODE=""            # Hostname or IP of this node
TARGET_HOSTS=""      # List of hosts/IPs for synchronization (space-separated).
                                     # Can be omitted on backup nodes.
SSH_USER="user"                      # User for synchronization (with administrator privileges)
SSH_ID="/home/$SSH_USER/.ssh/id_rsa" # Path to private key
```

#### NOTE
For cross-synchronization,
fill in the `TARGET_HOSTS` list on all nodes;
however, do not include the current node
that is currently being configured in the list.



### Configuring Health Checks for Angie

Add a health check block to the Angie configuration
(`/etc/angie/angie.conf`):

```ini
server {

    listen unix:/tmp/angie_hcheck.sock; # Unix socket for checking
    access_log off;
    error_log /dev/null;
    default_type text/plain;
    return 200 'ok\n';
}
```

Start Angie:

```console
$ sudo angie -t && sudo service angie start
```

Start synchronization:

```console
$ sudo angiehasync -Sd
```

#### NOTE
The script will automatically check the configuration, perform synchronization with all
nodes, and apply it.



## Configuring Keepalived

For automatic failover between cluster nodes, Keepalived is used —
a service for managing virtual IP addresses (VIP).

#### NOTE
If the `keepalived` package is not installed — install it:

```console
$ sudo {apk|apt|pkg|yum|zypper} {add|install} keepalived
```

To bind processes to non-local IP addresses,
allow the system to perform corresponding actions:

```console
$ sudo sysctl -w net.ipv4.ip_nonlocal_bind=1
```

More details:
[https://www.kernel.org/doc/Documentation/networking/ip-sysctl.txt#ip_nonlocal_bind](https://www.kernel.org/doc/Documentation/networking/ip-sysctl.txt#ip_nonlocal_bind)

Suppose VIP `10.21.11.230`
is assigned either to the master node (`10.21.8.26`)
or to the backup (`10.21.8.27`).

If Angie listens on this VIP (`listen 10.21.11.230:80;`)
but the address is not yet assigned,
Angie will not be able to start without the `ip_nonlocal_bind` parameter.



### Keepalived Configuration

On the master node (`/etc/keepalived/keepalived.conf`):

```ini
global_defs {
    enable_script_security
}

vrrp_script angie_check {
    script "/usr/bin/curl -s --connect-timeout 5 -A 'angie_hcheck_script'
    --no-buffer -XGET --unix-socket /tmp/angie_hcheck.sock http://hcheck/"
    interval 5 user angie
}

vrrp_instance angie {
    state MASTER interface enp0s2 virtual_router_id 254 priority 100
    advert_int 2 unicast_src_ip 10.21.8.26

    unicast_peer {
        10.21.8.27
    }

    virtual_ipaddress {
        10.21.11.230
    } track_script {
        angie_check
    }
}
```

On the backup node:

```ini
global_defs {
    enable_script_security
}

vrrp_script angie_check {
    script "/usr/bin/curl -s --connect-timeout 5 -A 'angie_hcheck_script'
    --no-buffer -XGET --unix-socket /tmp/angie_hcheck.sock http://hcheck/"
    interval 5 user angie
}

vrrp_instance angie {
    state MASTER interface enp0s2 virtual_router_id 254 priority 99
    advert_int 2 unicast_src_ip 10.21.8.27

    unicast_peer {
        10.21.8.26
    }

    virtual_ipaddress {
        10.21.11.230
    } track_script {
        angie_check
    }
}
```

#### NOTE
In the `vrrp_instance angie` section, set the following values:

- `unicast_src_ip` — IP of the current node
- `unicast_peer` — IP of neighboring nodes
- `virtual_ipaddress` — virtual IP (VIP)
- `interface` — network interface

Start the service:

```console
$ sudo keepalived -t && sudo service keepalived start
```



### Keepalived Configuration Breakdown

Let's examine the main elements of the Keepalived configuration in detail
to understand the cluster operation principles.

The configuration includes two parts:

- `global_defs` — global settings
- `vrrp_instance` — VRRP parameters (VIP switching)

Main elements:

- `enable_script_security` — allows execution of health check scripts
- `vrrp_script` — Angie health check script
- `state MASTER` — initial node state
- `priority` — priority (MASTER role is assigned to the highest)
- `advert_int` — VRRP advertisement interval
- `unicast_src_ip` — current node IP
- `unicast_peer` — neighbor IPs
- `virtual_ipaddress` — VIP address
- `track_script` — availability monitoring via health check scripts

#### NOTE
If the original master node recovers,
it will regain the MASTER role (higher priority).
To disable failback, use the `nopreempt` parameter:

```none
vrrp_instance angie {
    ... nopreempt
}
```



## Testing Cluster Operation

After completing the configuration, it's necessary to test the cluster operation
and ensure correct switching between nodes.

Check VIP status:

```console
$ ip addr show enp0s2 | grep "10.21.11.230"
```

Test fault tolerance:

Stop Angie on the master node:

```console
$ sudo service angie stop
```

Check VIP transition to the backup node:

```console
$ ip addr show enp0s2 | grep "10.21.11.230"
```

Start Angie on the master node again:

```console
$ sudo service angie start
```

After this, the VIP should return to the master node.


# https://en.angie.software/angie/docs/configuration/oidc.md





# OIDC Authentication Setup

This guide explains how to set up OpenID Connect (OIDC) authentication
using Google as the identity provider
and Angie web server with Lua scripting.

The implementation protects internal endpoints with OAuth2/OIDC authentication
and demonstrates one way to restrict access based on email domains.
This is just one example approach; you can implement access control however you prefer,
such as maintaining allowlists of specific users, checking for realm membership
or group attributes in the provider response, or using custom claims from your
private IAM system.



## Architecture

The OIDC setup suggested here consists of:

- Angie - with Lua module support for OIDC processing
- [lua-resty-openidc](https://github.com/zmartzone/lua-resty-openidc) - OpenResty Lua library for OIDC authentication
- Google OAuth2 - Identity provider for user authentication
- Docker Compose - Used in this example for rapid startup only;
  use whatever deployment approach you prefer in production



## Prerequisites

Before configuring OIDC authentication, ensure you have:

1. Angie web server with [Lua](https://en.angie.software//angie/docs/configuration/modules/external-modules/lua.md#external-lua) module support
2. Docker and Docker Compose (for deployment)
3. A Google Cloud Console project
4. OAuth2 credentials from Google



## Google OAuth2 Setup

To configure Google as your OIDC provider:

1. Navigate to the [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
2. Create a new project or select an existing one
3. Configure the OAuth consent screen for your project (External or Internal) and publish it so users can authenticate
4. Create OAuth2 credentials:
   - Application type: Web application
   - Authorized redirect URIs: `http://localhost/auth/callback`
5. Save your `client_id` and `client_secret` for configuration

#### NOTE
Standard Google Identity Services already support OIDC; the legacy Google+ API is not required.
Enable additional Google APIs only if your application needs their data.



## Configuration Setup

Let's start with the configuration files needed for the OIDC setup.



### Docker Compose Configuration

The Docker deployment uses the following configuration file:

```yaml
services:
  angie:
    image: docker.angie.software/angie:templated
    environment:
      ANGIE_LOAD_MODULES: "lua"
    ports:
      - 80:80
    volumes:
      - ./files/etc/angie/http.d:/etc/angie/http.d
```

This configuration does the following:

- Uses the [templated Angie image](https://en.angie.software//angie/docs/installation/docker.md#docker-templated) with Lua module support
- Loads the [Lua](https://en.angie.software//angie/docs/configuration/modules/external-modules/lua.md#external-lua) module for OIDC functionality
- Maps port 80 for HTTP access
- Mounts configuration files from local directory

For a plug-and-play demo,
download the [`OIDC quick-start bundle`](https://en.angie.software//angie/docs/configuration/oidc-sample-config.zip),
set your `client_id` and `client_secret` in `files/etc/angie/http.d/oidc.lua`,
and everything will work out of the box.



### OIDC Authentication Script

Create an OIDC authentication script
that handles the authentication logic using the `lua-resty-openidc` library:

```lua
access_by_lua_block {
    local res, err = require("resty.openidc").authenticate({
        redirect_uri = "http://localhost/auth/callback",
        discovery = "https://accounts.google.com/.well-known/openid-configuration",
        logout_path = "/auth/logout",
        redirect_after_logout_uri = "/auth/logged-out",
        revoke_tokens_on_logout = true,
        client_id = "YOUR_CLIENT_ID",
        client_secret = "YOUR_CLIENT_SECRET"
    })
}
```

Configuration parameters:

- `redirect_uri`: Callback URL after successful authentication
- `discovery`: Google's OIDC discovery endpoint
- `logout_path`: Path for user logout
- `redirect_after_logout_uri`: Redirect destination after logout
- `revoke_tokens_on_logout`: Revoke tokens on logout for security
- `client_id` and `client_secret`: Your Google OAuth2 credentials



### Angie Configuration

Configure Angie with the necessary [location](https://en.angie.software//angie/docs/configuration/modules/http/index.md#location) blocks
for OIDC authentication.



#### Protected Resources

To protect resources with OIDC authentication:

```nginx
location /internal/ {
    include /etc/angie/http.d/oidc.lua;
    proxy_pass http://127.0.0.1/status/;
}
```

This configuration does the following:

- Protects the `/internal/` path with OIDC authentication
- Proxies authenticated requests to the [internal API](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#http-api)
  at `/status/`



#### Authentication Endpoints

Configure the OAuth2 flow endpoints:

```nginx
location /auth/callback {
    include /etc/angie/http.d/oidc.lua;
}

location /auth/logout {
    include /etc/angie/http.d/oidc.lua;
}

location /auth/logged-out {
    default_type text/plain;
    return 200 "You have been logged out. Bye!";
}
```

Endpoint functions:

- `/auth/callback`: Handles OAuth2 callback from Google
- `/auth/logout`: Initiates user logout
- `/auth/logged-out`: Landing page after successful logout



#### Internal API Access

Configure restricted access to the internal API:

```nginx
location /status/ {
    api     /status/;
    allow   127.0.0.1;
    deny    all;
}
```

This provides:

- Access to Angie's [status API](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#http-api)
- Localhost-only access (127.0.0.1)
- OIDC protection when accessed through `/internal/`



## Deployment Steps

Follow these steps to deploy OIDC authentication:



### Configuration Update

1. Update OAuth2 credentials in your OIDC Lua script:

   Replace the placeholder values in `oidc.lua`:
   - `client_id` with your Google OAuth2 client ID
   - `client_secret` with your Google OAuth2 client secret



### Service Startup

1. Start the Docker services:
   ```console
   $ docker-compose up -d
   ```
2. Verify the deployment:
   - Navigate to `http://localhost/internal/`
   - You should be redirected to Google for authentication
   - After successful login, you'll access the protected content



## Security Configuration



### Email Domain Restriction

Implement domain validation to restrict access by email domain:

```lua
if not string.match(res.user.email, "gmail.com$") then
    ngx.exit(ngx.HTTP_FORBIDDEN)
end
```

For production environments, consider the following:

- Replacing `gmail.com` with your organization's domain
- Implementing a whitelist of allowed email addresses
- Adding role-based access control



### Token Management

The OIDC implementation includes security features:

- Tokens are automatically revoked on logout (`revoke_tokens_on_logout = true`)
- Sessions are managed securely by the lua-resty-openidc library
- All authentication flows follow OAuth2/OIDC security best practices

#### WARNING
For production deployments:

- Always use HTTPS for OAuth2 callbacks
- Store client secrets securely, never in version control
- Implement proper session timeouts and renewal policies
- Monitor authentication logs for security events



## Authentication Flow

The OIDC authentication flow follows standard OAuth2/OIDC procedures:

1. User accesses a protected URL (e.g., `http://localhost/internal/`)
2. If not authenticated, user is redirected to Google OAuth2
3. User authenticates with Google credentials
4. Google redirects back to `/auth/callback` with authorization code
5. Server exchanges code for access token and ID token
6. User information is validated (including email domain check)
7. User is granted access to protected resource

The logout process ensures secure session termination:

1. User navigates to `http://localhost/auth/logout`
2. Tokens are revoked at Google's OAuth2 endpoint
3. Local session data is cleared
4. User is redirected to `/auth/logged-out`



## Advanced Configuration

To restrict access to a specific organization domain:

```lua
if not string.match(res.user.email, "yourcompany.com$") then
    ngx.exit(ngx.HTTP_FORBIDDEN)
end
```

For organizations with multiple allowed domains:

```lua
local allowed_domains = {"company1.com", "company2.com", "gmail.com"}
local email_valid = false

for _, domain in ipairs(allowed_domains) do
    if string.match(res.user.email, domain .. "$") then
        email_valid = true
        break
    end
end

if not email_valid then
    ngx.exit(ngx.HTTP_FORBIDDEN)
end
```



### User Information Access

Access additional user claims from the OIDC provider:

```lua
-- Access user information from ID token
local user_name = res.user.name
local user_picture = res.user.picture
local user_locale = res.user.locale
local user_email = res.user.email
```

These values can be used for logging, personalization, or additional
access control decisions.


# https://en.angie.software/angie/docs/configuration/ssl.md





# SSL Configuration

To configure an HTTPS server, the [ssl](https://en.angie.software//angie/docs/configuration/modules/http/index.md#listen) parameter must be enabled
on listening sockets in the [server](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server) block, and the locations of the server
certificate and private key files should be specified:

```nginx
server {
    listen              443 ssl;
    server_name         www.example.com;
    ssl_certificate     www.example.com.crt;
    ssl_certificate_key www.example.com.key;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         HIGH:!aNULL:!MD5;
#...
}
```

The server certificate is a public entity. It is sent to every client that
connects to the server. The private key is a secure entity and should be stored
in a file with restricted access; however, it must be readable by Angie's
master process. The private key may alternately be stored in the same file as
the certificate.

```nginx
ssl_certificate     www.example.com.cert;
ssl_certificate_key www.example.com.cert;
```

In which case the file access rights should also be restricted. Although the
certificate and the key are stored in one file, only the certificate is sent to
a client.

The directives [ssl_protocols](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-protocols) and [ssl_ciphers](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-ciphers) can be used to limit
connections to include only the strong versions and ciphers of SSL/TLS. By
default, Angie uses:

```nginx
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers HIGH:!aNULL:!MD5;
```

So configuring them explicitly is generally not needed.



## HTTPS Server Optimization

SSL operations consume extra CPU resources. On multi-processor systems, several
[worker processes](https://en.angie.software//angie/docs/configuration/modules/core.md#worker-processes) should be run, no less than the
number of available CPU cores. The most CPU-intensive operation is the SSL
handshake. There are two ways to minimize the number of these operations per
client: the first is by enabling [keepalive](https://en.angie.software//angie/docs/configuration/modules/http/index.md#keepalive-timeout)
connections to send several requests via one connection, and the second is to
reuse SSL session parameters to avoid SSL handshakes for parallel and subsequent
connections. The sessions are stored in an SSL session cache shared between
workers and configured by the [ssl_session_cache](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-session-cache) directive. One megabyte
of the cache contains about 4000 sessions. The default cache timeout is 5
minutes. It can be increased by using the [ssl_session_timeout](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-session-timeout) directive.
Here is a sample configuration optimized for a multi-core system with a
10-megabyte shared session cache:

```nginx
worker_processes auto;

http {
    ssl_session_cache   shared:SSL:10m;
    ssl_session_timeout 10m;

    server {
        listen              443 ssl;
        server_name         www.example.com;
        keepalive_timeout   70;

        ssl_certificate     www.example.com.crt;
        ssl_certificate_key www.example.com.key;
        ssl_protocols       TLSv1.2 TLSv1.3;
        ssl_ciphers         HIGH:!aNULL:!MD5;
    #...
```



## SSL Certificate Chains

Some browsers may complain about a certificate signed by a well-known
certificate authority, while other browsers may accept the certificate without
issues. This occurs because the issuing authority has signed the server
certificate using an intermediate certificate that is not present in the
certificate base of well-known trusted certificate authorities distributed with
a particular browser. In this case, the authority provides a bundle of chained
certificates which should be concatenated to the signed server certificate. The
server certificate must appear before the chained certificates in the combined
file:

```console
$ cat www.example.com.crt bundle.crt > www.example.com.chained.crt
```

The resulting file should be used with the [ssl_certificate](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-certificate) directive:

```nginx
server {
    listen              443 ssl;
    server_name         www.example.com;
    ssl_certificate     www.example.com.chained.crt;
    ssl_certificate_key www.example.com.key;
#...
}
```

If the server certificate and the bundle were concatenated in the wrong order,
Angie fails to start and displays an error message:

> SSL_CTX_use_PrivateKey_file(" ... /www.example.com.key") failed
> : (SSL: error:0B080074:x509 certificate routines:
>   X509_check_private_key:key values mismatch)

Because Angie tried to use the private key with the bundle's first
certificate instead of the server certificate.

Browsers usually store intermediate certificates that they receive, signed by
trusted authorities, so browsers that are actually used may already have the
required intermediate certificates and may not complain about a certificate
being sent without a chained bundle. To ensure the server sends the complete
certificate chain, the **openssl** command-line utility may be used, for
example:

```console
$ openssl s_client -connect www.godaddy.com:443

Certificate chain
 0 s:/C=US/ST=Arizona/L=Scottsdale/1.3.6.1.4.1.311.60.2.1.3=US
     /1.3.6.1.4.1.311.60.2.1.2=AZ/O=GoDaddy.com, Inc
     /OU=MIS Department/CN=www.GoDaddy.com
     /serialNumber=0796928-7/2.5.4.15=V1.0, Clause 5.(b)
   i:/C=US/ST=Arizona/L=Scottsdale/O=GoDaddy.com, Inc.
     /OU=http://certificates.godaddy.com/repository
     /CN=Go Daddy Secure Certification Authority
     /serialNumber=07969287
 1 s:/C=US/ST=Arizona/L=Scottsdale/O=GoDaddy.com, Inc.
     /OU=http://certificates.godaddy.com/repository
     /CN=Go Daddy Secure Certification Authority
     /serialNumber=07969287
   i:/C=US/O=The Go Daddy Group, Inc.
     /OU=Go Daddy Class 2 Certification Authority
 2 s:/C=US/O=The Go Daddy Group, Inc.
     /OU=Go Daddy Class 2 Certification Authority
   i:/L=ValiCert Validation Network/O=ValiCert, Inc.
     /OU=ValiCert Class 2 Policy Validation Authority
     /CN=http://www.valicert.com//emailAddress=info@valicert.com
```

In this example, the subject ("s") of the www.GoDaddy.com server certificate #0
is signed by an issuer ("i") which itself is the subject of the certificate #1,
which is signed by an issuer which itself is the subject of the certificate #2,
which is signed by the well-known issuer ValiCert, Inc. whose certificate is
stored in the browsers' built-in certificate base.

If a certificate bundle has not been added, only the server certificate #0 will
be shown.



## A Single HTTP/HTTPS Server

It is possible to configure a single server that handles both HTTP and HTTPS
requests:

```nginx
server {
    listen              80;
    listen              443 ssl;
    server_name         www.example.com;
    ssl_certificate     www.example.com.crt;
    ssl_certificate_key www.example.com.key;
#...
}
```



## Name-Based HTTPS Servers

A common issue arises when configuring two or more HTTPS servers listening on a
single IP address:

```nginx
server {
    listen          443 ssl;
    server_name     www.example.com;
    ssl_certificate www.example.com.crt;
#...
}

server {
    listen          443 ssl;
    server_name     www.example.org;
    ssl_certificate www.example.org.crt;
#...
}
```

With this configuration, a browser receives the default server's certificate,
i.e. www.example.com, regardless of the requested server name. This is caused
by SSL protocol behavior. The SSL connection is established before the browser
sends an HTTP request, and Angie does not know the name of the requested
server. Therefore, it may only offer the default server's certificate.



The oldest and most robust method to resolve the issue is to assign a separate
IP address for every HTTPS server:

```nginx
server {
    listen          192.168.1.1:443 ssl;
    server_name     www.example.com;
    ssl_certificate www.example.com.crt;
#...
}

server {
    listen          192.168.1.2:443 ssl;
    server_name     www.example.org;
    ssl_certificate www.example.org.crt;
#...
}
```



## An SSL Certificate with Multiple Names

There are other ways that allow sharing a single IP address between several
HTTPS servers. However, all of them have their drawbacks. One way is to use a
certificate with several names in the `SubjectAltName` certificate field, for
example, `www.example.com` and `www.example.org`. However, the `SubjectAltName`
field length is limited.

Another way is to use a certificate with a wildcard name, for example,
`*.example.org`. A wildcard certificate secures all subdomains of the
specified domain, but only on one level. This certificate matches
`www.example.org` but does not match `example.org` and
`www.sub.example.org`. These two methods can also be combined. A
certificate may contain exact and wildcard names in the `SubjectAltName`
field, for example, `example.org` and `*.example.org`.

It is better to place a certificate file with several names and its private key
file at the `http` level of configuration to inherit their single memory
copy in all servers:

```nginx
ssl_certificate     common.crt;
ssl_certificate_key common.key;

server {
    listen          443 ssl;
    server_name     www.example.com;
#...
}

server {
    listen          443 ssl;
    server_name     www.example.org;
#...
}
```



## Server Name Indication

A more generic solution for running several HTTPS servers on a single IP address
is TLS Server Name Indication extension (SNI, [RFC 6066](https://datatracker.ietf.org/doc/html/rfc6066.html)), which allows a browser
to pass a requested server name during the SSL handshake, and therefore, the
server will know which certificate it should use for the connection. SNI is
currently supported by most modern browsers, though may not be used by some old
or special clients.

If Angie was built with SNI support, then Angie will show this when run with the
`-V` switch:

```console
$ angie -V
...
TLS SNI support enabled
...
```

However, if the SNI-enabled Angie is linked dynamically to an OpenSSL
library without SNI support, Angie displays a warning:

> Angie was built with SNI support, however, now it is linked
> dynamically to an OpenSSL library which has no tlsext support,
> therefore SNI is not available


# https://en.angie.software/angie/docs/configuration/monitoring.md





# Console Light Web Monitoring Panel

Angie provides a wide range of possibilities to monitor its work; in
addition to the [metrics](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#metrics) API and the [Prometheus](https://en.angie.software//angie/docs/configuration/modules/http/http_prometheus.md#http-prometheus) module, you can use a visual console that installs beside the
server.



## Console Light

Console Light is a lightweight, real-time activity monitoring interface that
displays key server load and performance metrics. The console is based on the [API
capabilities](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#http-api) of Angie; activity monitoring data is generated in real
time. In addition, the console allows you to dynamically [modify](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-config) Angie configuration where the API itself provides this
capability.

Example of a deployed and configured console: [https://console.angie.software/](https://console.angie.software/)



## Version History

| Version   | Release Date   | Changes                                                                                                                                                                                                                                                                                                                                                                                                                                        |
|-----------|----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 1.9.0     | 14.08.2026     | Added display of the `draining` and `recovering` states
in the server tooltip.                                                                                                                                                                                                                                                                                                                                                             |
| 1.8.2     | 23.01.2026     | Fixed the link to Angie ADC documentation.                                                                                                                                                                                                                                                                                                                                                                                                     |
| 1.8.1     | 08.09.2025     | Fixed incorrect terms in Settings and tooltips.                                                                                                                                                                                                                                                                                                                                                                                                |
| 1.8.0     | 03.07.2025     | Display of response time metrics
for proxied HTTP and TCP/UDP servers                                                                                                                                                                                                                                                                                                                                                                      |
| 1.7.2     | 07.04.2025     | Added "busy" option in filter controller on the HTTP/TCP/UDP Upstreams
pages.                                                                                                                                                                                                                                                                                                                                                              |
| 1.7.1     | 04.04.2025     | Fixed incorrect values in the HTTP/Location Zones tables on the HTTP
Zones page.                                                                                                                                                                                                                                                                                                                                                           |
| 1.7.0     | 02.04.2025     | - Display exact data volumes in bytes on mouse hover
- New `busy` status for upstream peers in the statistics API,
  indicating that a peer has reached the limit configured by the `max_conns` parameter
- Fixed documentation links                                                                                                                                                                                              |
| 1.6.1     | 27.01.2025     | - Fixed typos
- Fixed a development-time project build issue                                                                                                                                                                                                                                                                                                                                                                               |
| 1.6.0     | 23.01.2025     | - Internationalization support with available locales: `en`, `ru`.
- Sticky header feature added to the table component.
- Support for data measurement units in pebibytes (PiB).
- Fixed incorrect value counter in the [HTTP Upstreams](#console-http-upstreams-widget) widget on the main page.
- Default values are now correctly used on the [HTTP Upstreams](#console-http-upstreams-page) page in the response context. |
| 1.5.0     |                | Not publicly released.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| 1.4.0     | 08.08.2024     | Added monitoring status display in the website favicon.                                                                                                                                                                                                                                                                                                                                                                                        |
| 1.3.0     | 28.04.2024     | Added the ability to set a server to the `draining` state
in the upstream context.                                                                                                                                                                                                                                                                                                                                                         |
| 1.2.1     | 26.12.2023     | Added active health checks in the `Stream` context.                                                                                                                                                                                                                                                                                                                                                                                            |
| 1.2.0     | 25.12.2023     | Added server editing in the `Stream` context.                                                                                                                                                                                                                                                                                                                                                                                                  |



## Installation and Configuration

Console Light is published as
`angie-console-light` (Angie)
and
`angie-pro-console-light` (Angie PRO)
packages in
[our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages)
and can be installed like any other package;
alternatively, you can download the source code
[from our website](https://download.angie.software/files/angie-console-light/)
or
[GitHub](https://github.com/webserver-llc/angie-console-light).

After installation,
configure the console by adding the following [location](https://en.angie.software//angie/docs/configuration/modules/http/index.md#location)
inside a [server](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server) block in the
[server configuration](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)
(note the comments):

```nginx
location /console/ {

    # Local access only
    allow 127.0.0.1;
    deny all;

    auto_redirect on;

    alias /usr/share/angie-console-light/html/;
    # FreeBSD only:
    # alias /usr/local/www/angie-console-light/html/;
    index index.html;

    location /console/api/ {
        api /status/;
    }

    # For editing features to work after authentication (PRO only)
    location /console/api/config/ {

        auth_basic           "Protected site";
        auth_basic_user_file conf/htpasswd;

        api /config/;
    }
}
```

Don't forget to apply the modified configuration:

```console
$ sudo angie -t && sudo service angie reload
```

After this, the console will be available
on the server specified by the `server` block,
at the path specified for the `location`;
in the example above, the path is set as `/console/`.

Authentication can be enabled for any API section
similar to the example above, for instance:

```nginx
location /console/server_zones/ {
    auth_basic           "Protected site";
    auth_basic_user_file conf/htpasswd;
}
```

You can also restrict access to any section
of the configured console `location`, for example:

```nginx
location /console/api/resolvers/ {
    deny all;
}
```



## Interface

The console is a single screen with a set of tabs,
each containing several widgets with monitoring data.



### Angie Tab

![Console Light - main screen](../../_images/console_light/en/main.webp)

This is the main tab where the key Angie monitoring indicators
are displayed in summary form, based on data from several API sections.

#### NOTE
Statistics widgets are displayed
if the corresponding blocks are configured in the [Angie configuration](https://en.angie.software//angie/docs/configuration/configfile.md#configfile).



#### About Widget

Displays the Angie version number with a link to the corresponding
documentation, as well as the server address and the time of the last [configuration
reload](https://en.angie.software//angie/docs/configuration/runtime.md#control-config-change).

Additionally, if the [api_config_files](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#a-api-config-files) directive is enabled,
the *Configs* link opens a list of configuration files
loaded on the server.
Each file can then be viewed in a compact format with syntax highlighting.



#### Connections Widget

Displays basic server connection statistics, generated from the
`/status/connections/` API section:

| `Current`    | Current number of connections             |
|--------------|-------------------------------------------|
| `Accepted/s` | Number of connections accepted per second |
| `Active`     | Number of active connections              |
| `Idle`       | Number of idle connections                |
| `Dropped`    | Number of dropped connections             |

Also available:

| `Accepted`   | Total number of connections accepted since the last server reload   |
|--------------|---------------------------------------------------------------------|



#### HTTP Zones Widget

#### WARNING
Requires setting the [status_zone](https://en.angie.software//angie/docs/configuration/modules/http/index.md#status-zone) directive
in a `server` or `location` context.

Displays shared memory zone statistics for the `http` context,
generated from the [/status/http/server_zones/](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-server-zones) API section:

| `Total`    | Total number of zones                                    |
|------------|----------------------------------------------------------|
| `Problems` | Number of zones with any issues                          |
| `Traffic`  | Incoming and outgoing traffic rates, in bytes per second |



#### HTTP Upstreams Widget

#### WARNING
Requires setting the [zone](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone) directive
in an [upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) block in the `http` context.

Displays upstream statistics for the `http` context, generated from the
[/status/http/upstreams/](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-upstreams) API section:

| Total    | Total number of upstreams              |
|----------|----------------------------------------|
| Problems | Number of upstreams with any issues    |
| Servers  | Server statistics broken down by state |



#### TCP/UDP Zones Widget

#### WARNING
Requires setting the following directives:

- `status_zone`
  in a [server](https://en.angie.software//angie/docs/configuration/modules/http/index.md#status-zone) or [stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#s-status-zone) context;
- `limit_conn`
  in a [server](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#limit-conn) or [stream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_limit_conn.md#s-limit-conn) context;
- [limit_conn_zone](https://en.angie.software//angie/docs/configuration/modules/http/http_limit_conn.md#limit-conn-zone) in the `stream` context.

Example:

```nginx
stream {

    # ...
    limit_conn_zone $connection zone=limit-conn-stream:10m;

    server {

        # ...
        limit_conn limit-conn-stream 1;
        status_zone foo;
    }
}
```

Displays shared memory zone statistics for the `stream` context,
generated from the [/status/stream/server_zones/](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-stream-server-zones) API section:

| Conn total   | Total number of client connections         |
|--------------|--------------------------------------------|
| Conn current | Current number of client connections       |
| Conn/s       | Number of connections processed per second |



#### TCP/UDP Upstreams Widget

#### WARNING
Requires setting the [zone](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-zone) directive
in an [upstream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-upstream) block in the `stream` context.

Displays upstream statistics for the `stream` context, generated from the
[/status/stream/upstreams/](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-stream-upstreams) API section:

| Total    | Total number of upstreams              |
|----------|----------------------------------------|
| Problems | Number of upstreams with any issues    |
| Servers  | Server statistics broken down by state |



### HTTP Zones Tab

#### WARNING
Requires setting the [status_zone](https://en.angie.software//angie/docs/configuration/modules/http/index.md#status-zone) directive
in a `server` or `location` context.



#### Server Zones Section

![Console Light — "Server Zones" section on the "HTTP Zones" tab](../../_images/console_light/en/http-server-zones.webp)

Summarizes shared memory zone monitoring statistics for the `server` context
in `http`, generated from the [/status/http/server_zones/](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-server-zones) API section. The following data is presented for
each zone:

| Zone      | Zone name                                                                                                                                |
|-----------|------------------------------------------------------------------------------------------------------------------------------------------|
| Requests  | Total number of requests and the number of requests per second                                                                           |
| Responses | Number of responses broken down by status codes,
as well as their total number                                                       |
| Traffic   | Outgoing and incoming traffic rates in bytes per second, as well as
total volumes of outgoing and incoming traffic in bytes          |
| SSL       | Aggregate counts of: successful SSL handshakes; SSL session reuses;
SSL handshakes with expired timeout; unsuccessful SSL handshakes |



#### Location Zones Section

![Console Light — "Location Zones" section on the "HTTP Zones" tab](../../_images/console_light/en/http-location-zones.webp)

Summarizes shared memory zone monitoring statistics for the `location` context
in `http`, generated from the [/status/http/location_zones/](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-location-zones) API section. The following data is presented for
each zone:

| Zone      | Zone name                                                                                                                       |
|-----------|---------------------------------------------------------------------------------------------------------------------------------|
| Requests  | Total number of requests and the number of requests per second                                                                  |
| Responses | Number of responses broken down by status codes,
as well as their total number                                              |
| Traffic   | Outgoing and incoming traffic rates in bytes per second, as well as
total volumes of outgoing and incoming traffic in bytes |



#### Connection Limit Zones (Limit Conn) Section

![Console Light — "Connection Limit Zones" section on the "HTTP Zones" tab](../../_images/console_light/en/http-limit-conn.webp)

Displays statistics of `limit_conn` zones in the `http` context, generated
from the [/status/http/limit_conns/](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-limit-conns) API section. The following data is presented for
each zone:

| Zone      | Zone name                                                                        |
|-----------|----------------------------------------------------------------------------------|
| Passed    | Total number of proxied connections                                              |
| Rejected  | Total number of rejected connections                                             |
| Exhausted | Total number of connections dropped due to zone storage overflow                 |
| Skipped   | Total number of connections passed with a zero or greater than 255
bytes key |



#### Request Limit Zones (Limit Req) Section

![Console Light — "Request Limit Zones" section on the "HTTP Zones" tab](../../_images/console_light/en/http-limit-req.webp)

Displays statistics of `limit_reqs` zones in the `http` context, generated
from the [/status/http/limit_reqs/](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-limit-reqs) API section. The
following data is presented for each zone:

| Zone      | Zone name                                                                        |
|-----------|----------------------------------------------------------------------------------|
| Passed    | Total number of proxied connections                                              |
| Delayed   | Total number of delayed connections                                              |
| Rejected  | Total number of rejected connections                                             |
| Exhausted | Total number of connections dropped due to zone storage overflow                 |
| Skipped   | Total number of connections passed with a zero or greater than 255
bytes key |



### HTTP Upstreams Tab

![Console Light — "HTTP Upstreams" tab](../../_images/console_light/en/http-upstreams.webp)

#### WARNING
Requires setting the [zone](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone) directive
in an [upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) block in the `http` context.

This tab summarizes upstream monitoring statistics for the `http` context,
generated from the [/status/http/upstreams/](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-upstreams)
API section. In debug mode, memory usage percentage is also displayed.

- The Show upstreams list button toggles a brief list of upstreams
  with the number of problematic upstreams and peers.
- The Failed only switch toggles the display mode for
  problematic upstreams statistics.
- The edit button toggles the upstream editing interface.
- The dropdown list on the right side of each upstream table allows you to
  filter servers in a specific state (Up, Failed, Checking,
  Down).

For each upstream, in addition to its name and shared memory zone utilization
ratio, the following data is presented:

| Server          | Names, total downtimes, and weights of upstream servers                                                                                                                                                              |
|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Requests        | Total number and processing rate of requests                                                                                                                                                                         |
| Responses       | Number of responses broken down by status codes                                                                                                                                                                      |
| Connections     | Number of active connections and their maximum limit, if set                                                                                                                                                         |
| Traffic         | Outgoing and incoming traffic rates in bytes per second, as well as
total volumes of outgoing and incoming traffic in bytes                                                                                      |
| Server checks   | Number of unsuccessful attempts to contact the server and the number of times
the server was considered unavailable (the `health` object in the API)                                                             |
| Health monitors | Total number of server checks, number of
unsuccessful checks, and the time of the last check                                                                                                                     |
| Response time   | Time from the beginning of the request to sending the first byte of the response;
total time from the beginning of the request to completion of sending the entire response
(the `health` object in the API) |



#### Editing upstreams

In Angie PRO, there is an edit button next to each upstream; when clicked,
it displays two more buttons:

| `Edit selected`   | Edit selected servers within an upstream. Allows you to
set the following parameters for all at once: `Weight`,
maximum connection limit (`Max_conns`), maximum failure
limit that marks a server as unavailable (`Max_fails`), time
window for counting failures for the maximum failure limit
(`Fail_timeout`), state (`active` – enabled,
`down` – disabled, or `draining` – only receives
requests from sessions previously bound through `sticky`).

You can also delete the selected servers here.

![Console Light — editing servers
on the "HTTP Upstreams" tab](../../_images/console_light/en/http_upstreams_edit_servers.webp)   |
|-------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `Add server`      | Add a server to the upstream. Allows you to set the following parameters:
address, backup server or not, `Weight`, maximum connection
limit (`Max_conns`), maximum failure limit that marks a server
as unavailable (`Max_fails`), failure counting time
window (`Fail_timeout`), state (`active` – enabled,
`down` – disabled, or `draining` – only receives
requests from sessions previously bound through `sticky`).

![Console Light — adding a server
on the "HTTP Upstreams" tab](../../_images/console_light/en/http_upstreams_add_server.webp)                                                                                                 |



### `TCP/UDP Zones` Tab

#### WARNING
Requires setting the following directives:

- `status_zone`
  in a [server](https://en.angie.software//angie/docs/configuration/modules/http/index.md#status-zone) or [stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#s-status-zone) context;
- `limit_conn`
  in a [server](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#limit-conn) or [stream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_limit_conn.md#s-limit-conn) context;
- [limit_conn_zone](https://en.angie.software//angie/docs/configuration/modules/http/http_limit_conn.md#limit-conn-zone) in the `stream` context.

Example:

```nginx
stream {

    # ...
    limit_conn_zone $connection zone=limit-conn-stream:10m;

    server {

        # ...
        limit_conn limit-conn-stream 1;
        status_zone foo;
    }
}
```



#### `TCP/UDP Zones` Section

![Console Light — "TCP/UDP Zones" tab](../../_images/console_light/en/stream-zones.webp)

Summarizes shared memory zone monitoring statistics for the `server` context
in `stream`, generated from the [/status/stream/server_zones/](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-stream-server-zones) API section. The following data is presented for
each zone:

| `Zone`        | Zone name                                                                                                                       |
|---------------|---------------------------------------------------------------------------------------------------------------------------------|
| `Connections` | Current and total number of connections, as well as the number of connections per
second                                    |
| `Sessions`    | Number of sessions broken down by status codes,
as well as their total number                                               |
| `Traffic`     | Outgoing and incoming traffic rates in bytes per second, as well as
total volumes of outgoing and incoming traffic in bytes |
| `SSL`         | Aggregate counts of: successful SSL handshakes; unsuccessful SSL handshakes;
SSL session reuses                             |



#### `Connection Limit Zones (Limit Conn)` Section

![Console Light — "Connection Limit Zones" section on the "TCP/UDP Zones" tab](../../_images/console_light/en/stream-limit-conn.webp)

Displays statistics of `limit_conn` zones in the `stream` context, generated
from the [/status/stream/limit_conns/](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-limit-conns) API section. The following data is presented for
each zone:

| `Zone`      | Zone name                                                                        |
|-------------|----------------------------------------------------------------------------------|
| `Passed`    | Total number of proxied connections                                              |
| `Rejected`  | Total number of rejected connections                                             |
| `Exhausted` | Total number of connections dropped due to zone storage overflow                 |
| `Skipped`   | Total number of connections passed with a zero or greater than 255
bytes key |



### `TCP/UDP Upstreams` Tab

![Console Light — "TCP/UDP Upstreams" tab](../../_images/console_light/en/stream-upstreams.webp)

#### WARNING
Requires setting the [zone](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-zone) directive
in an [upstream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-upstream) block in the `stream` context.

This tab summarizes upstream monitoring statistics for the `stream` context,
generated from the [/status/stream/upstreams/](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-stream-upstreams) API section.
In debug mode, memory usage percentage is also displayed.

- The `Show upstreams list` button toggles the display of a brief list of upstreams
  with the number of problematic upstreams and peers.
- The `Failed only` switch enables and disables the display mode for
  problematic upstreams statistics.
- The edit button opens the `upstream editing` widget.
- The dropdown list on the right side of each upstream table allows you to
  filter servers in a specific state (`Up`, `Failed`, `Checking`,
  `Down`).

For each upstream, the following data is presented:

| `Server`          | Names, total downtimes, and weights of upstream servers                                                                                                                                                                                                                               |
|-------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `Connections`     | Number of active connections and their maximum limit, if set                                                                                                                                                                                                                          |
| `Traffic`         | Outgoing and incoming traffic rates in bytes per second, as well as
total volumes of outgoing and incoming traffic in bytes                                                                                                                                                       |
| `Server checks`   | Number of unsuccessful attempts to contact the server and the number of times
the server was considered unavailable (the `health` object in the API)                                                                                                                              |
| `Health monitors` | Total number of server checks, number of
unsuccessful checks, and the time of the last check                                                                                                                                                                                      |
| `Response time`   | Time spent establishing a connection to the backend;
time from the beginning of the request to receiving the first byte of the response;
total time elapsed from the beginning of the request to receiving the last byte of the response
(the `health` object in the API) |



#### Editing upstreams

In Angie PRO, there is an edit button next to each upstream; when clicked,
it displays two more buttons:

| `Edit selected`   | Edit selected servers within an upstream. Allows you to
set the following parameters for all at once: `Weight`,
maximum connection limit (`Max_conns`), maximum failure
limit that marks a server as unavailable (`Max_fails`), time
window for counting failures for the maximum failure limit
(`Fail_timeout`), state (`active` – enabled,
`down` – disabled, or `draining` – only receives
requests from sessions previously bound through `sticky`).

You can also delete the selected servers here.

![Console Light – editing servers
on the "TCP/UDP Upstreams" tab](../../_images/console_light/en/http_upstreams_edit_servers.webp)   |
|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `Add server`      | Add a server to the upstream. Allows you to set the following parameters:
address, backup server or not, `Weight`, maximum connection
limit (`Max_conns`), maximum failure limit that marks a server
as unavailable (`Max_fails`), failure counting time
window (`Fail_timeout`), state (`active` – enabled,
`down` – disabled, or `draining` – only receives
requests from sessions previously bound through `sticky`).

![Console Light – adding a server
on the "TCP/UDP Upstreams" tab](../../_images/console_light/en/http_upstreams_add_server.webp)                                                                                                 |



### `Caches` Tab

![Console Light – "Caches" tab](../../_images/console_light/en/caches.webp)

#### WARNING
Requires setting the [proxy_cache_path](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-path) directive
in the `http` context.

This tab summarizes monitoring statistics for `proxy_cache` zones in the `http`
context, generated from the [/status/http/caches/](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-caches) API
section. The following data is presented for each zone:

| `Zone`         | Zone name                                                                                   |
|----------------|---------------------------------------------------------------------------------------------|
| `State`        | Cache state: cold (metadata being loaded into memory) or warm
(metadata loaded)         |
| `Memory usage` | Memory utilization ratio                                                                    |
| `Max size`     | Maximum cache size on disk, in bytes; the infinity sign if the cache
size isn't limited |
| `Used`         | Current cache size on disk, in bytes                                                        |
| `Disk usage`   | Disk utilization ratio                                                                      |
| `Traffic`      | Traffic served from cache, written to cache, and returned bypassing
the cache, in bytes |
| `Hit ratio`    | Cache hit ratio (ratio of traffic served from cache to
total volume)                    |

For a [sharded](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache) zone, `Max size`, `Used`, and
`Disk usage` are tracked per shard; the zone's own row shows dashes, and
the zone is displayed as a dropdown list of individual shards:

| `Path`       | Shard path on disk                                                                          |
|--------------|---------------------------------------------------------------------------------------------|
| `State`      | Shard state: cold (metadata being loaded into memory) or warm
(metadata loaded)         |
| `Max size`   | Maximum shard size on disk, in bytes; the infinity sign if the shard
size isn't limited |
| `Used`       | Current shard size on disk, in bytes                                                        |
| `Disk usage` | Disk utilization ratio                                                                      |



### `Shared Zones` Tab

![Console Light – "Shared Zones" tab](../../_images/console_light/en/shared_zones.webp)

This tab summarizes monitoring statistics for **all** shared memory zones
across all contexts. The following data is presented for each zone:

| `Zone`               | Zone name                             |
|----------------------|---------------------------------------|
| `Total memory pages` | Total number of memory pages          |
| `Used memory pages`  | Number of memory pages used           |
| `Memory usage`       | Memory utilization ratio for the zone |



### `DNS Resolvers` Tab

![Console Light – "Resolvers" tab](../../_images/console_light/en/resolvers.webp)

#### WARNING
Requires setting the [resolver](https://en.angie.software//angie/docs/configuration/modules/http/index.md#resolver) directive
in the `http` context.

This tab summarizes query statistics in DNS shared memory zones,
generated from the [/status/resolvers/](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-resolvers) API section.
The following data is presented for each zone:

| `Zone`      | Zone name                                                                                                                                                               |
|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `Requests`  | Number of A and AAAA, SRV, PTR type requests                                                                                                                            |
| `Responses` | Number of responses broken down by corresponding codes
(`Success`, `Format error`, `Server failure`,
`Name error`, `Not implemented`,
`Refused` and others) |



### `Settings` Widget

![Console Light – "Settings" widget](../../_images/console_light/en/cog.webp)

Allows you to configure general console parameters:

- Data refresh rate. Default value – 1 sec.
- Threshold ratio for `4xx` statuses. When the threshold is reached,
  "yellow" warnings appear in the corresponding sections related to server responses.
  Default value – 7%.
- Time window for calculating the cache hit ratio. Default
  value – 300 sec.
- Error threshold for the resolver. When the threshold is reached, the resolver
  will turn "red". Default value – 3%.
- Console interface language. Available options: English and Russian.
  By default, the console language is selected based on the locale set in
  the browser.



### Console Control Panel

On all tabs, in the middle of the left side of the page, there is a slide-out panel with
two buttons ![Console Light – console control buttons on the "About" tab](../../_images/console_light/en/play.webp). The top button pauses and resumes data updates from the API,
while the bottom button allows you to update the data manually when updates are
paused.


# https://en.angie.software/angie/docs/configuration/custom-metrics.md





# Custom Metrics Configuration

Angie can collect custom numeric metrics in shared memory and expose them via
the real-time [statistics API](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#metrics) at
`/status/http/metric_zones/`. This is provided by the
[Metric](https://en.angie.software//angie/docs/configuration/modules/http/http_metric.md#http-metric) module.

#### NOTE
This guide covers metrics for HTTP traffic. For TCP and UDP traffic, see
the Stream [Metric](https://en.angie.software//angie/docs/configuration/modules/stream/stream_metric.md#stream-metric) module, which exposes its zones
at `/status/stream/metric_zones/`.



## Configuration Steps

1. Define a metric zone in the `http` block:
   - [metric_zone](https://en.angie.software//angie/docs/configuration/modules/http/http_metric.md#metric-zone) creates a zone with a single metric mode.
   - [metric_complex_zone](https://en.angie.software//angie/docs/configuration/modules/http/http_metric.md#metric-complex-zone) creates a zone with multiple named metrics.
2. Update metrics in request processing with the [metric](https://en.angie.software//angie/docs/configuration/modules/http/http_metric.md#id1) directive.
   Use a `key=value` pair (both are [complex values](https://en.angie.software//angie/docs/configuration/configfile.md#string-variables)), and
   choose the update stage with `on=` (`request`, `response`,
   or `end`).
3. Expose the API with a `location`:
   ```nginx
   location /status/ {
       api /status/http/metric_zones/;
   }
   ```



## Example

Count requests per host and expose the metrics in the API:

```nginx
http {
    metric_zone requests:128k count;

    server {
        listen 80;

        location / {
            metric requests $host=1;
        }

        location /status/ {
            api /status/http/metric_zones/;
        }
    }
}
```



## Notes

- If `expire=on` is set on the zone and the shared memory is full, the
  least recently used entries are expired. If `expire=off`, new updates
  are discarded and the `discarded` counter grows.
- If `discard_key` is set, metrics from expired entries are aggregated
  under that key in the API output.
- Keys and values are limited to 255 bytes; longer keys are truncated in the API.
- An empty value is treated as `0`, and a non-empty value without a
  leading number is treated as `1`.


# https://en.angie.software/angie/docs/configuration/migration.md





# Migrating from nginx to Angie

If you're switching from nginx to Angie, congratulations!
We have a guide for you.

Keep in mind that it's tailored for a basic replacement scenario
that relies on a packaged version of Angie.
If you're working with [containers](https://en.angie.software//angie/docs/installation/docker.md#docker-images),
virtual machines, custom paths, or
[modules](https://en.angie.software//angie/docs/installation/index.md#install-dynamicmodules),
you'll need additional adjustments.



## Installing Angie

We recommend using the official packages
from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages);
see the installation steps for Angie for your distribution.
Don't start the server yet;
instead, check it with the command **sudo angie -V**:

```console
$ sudo angie -V

  Angie version: Angie/1.12.1
  nginx version: nginx/1.31.2
  built by gcc 11.4.0
  configure arguments: --prefix=/etc/angie --conf-path=/etc/angie/angie.conf ...
```

As this shows,
the [configuration](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)
is located in `/etc/angie/`
when Angie is installed from a package.



## Updating Angie Configuration

Angie usually requires minimal changes to existing nginx configuration.

1. Copy the entire nginx configuration to `/etc/angie/`:
   ```console
   $ sudo rsync -a --no-links /etc/nginx/ /etc/angie/
   ```

   We assume nginx configuration is stored in `/etc/nginx/`;
   adjust the steps if you have a different path.
2. Rename the main configuration file as Angie expects:
   ```console
   $ sudo mv /etc/angie/nginx.conf /etc/angie/angie.conf
   ```
3. Update paths throughout the Angie configuration,
   starting with the main configuration file.
   Details depend on how nginx was installed,
   but at minimum you need to update the following.

   Any [include](https://en.angie.software//angie/docs/configuration/modules/core.md#include) paths that still point to `/etc/nginx/`:
   ```nginx
   # include /etc/nginx/conf.d/*.conf;
   # include /etc/nginx/default.d/*.conf;
   # include /etc/nginx/http.d/*.conf;
   # include /etc/nginx/stream.d/*.conf;
   include /etc/angie/conf.d/*.conf;
   include /etc/angie/default.d/*.conf;
   include /etc/angie/http.d/*.conf;
   include /etc/angie/stream.d/*.conf;

   # include /etc/nginx/sites-enabled/*;
   include /etc/angie/sites-enabled/*;

   # include /etc/nginx/modules-enabled/*;
   include /etc/angie/modules-enabled/*;

   # include /etc/nginx/mime.types;
   include /etc/angie/mime.types;
   ```

   The [PID](https://en.angie.software//angie/docs/configuration/modules/core.md#pid) file, which is important for Angie process management:
   ```nginx
   # pid /var/run/nginx.pid;
   # -- or --
   # pid /run/nginx.pid;
   pid /run/angie.pid;
   ```

   Finally,
   [access log](https://en.angie.software//angie/docs/configuration/modules/http/http_log.md#access-log) and [error log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log):
   ```nginx
   # access_log /var/log/nginx/access.log;
   access_log /var/log/angie/access.log;

   # error_log /var/log/nginx/error.log;
   error_log /var/log/angie/error.log;
   ```



### Virtual Hosts

If the `sites-enabled/` directory is used to include virtual hosts,
update it as well:

```nginx
# include /etc/nginx/sites-enabled/*;
include /etc/angie/sites-enabled/*;
```

Then recreate the symlinks in `/etc/angie/sites-enabled/`
to make everything work.

List the original virtual host files, for example:

```console
$ ls -l /etc/nginx/sites-enabled/

  default -> /etc/nginx/sites-available/default
```

Note their actual location;
here it's `/etc/nginx/sites-available/`.

If you didn't copy them to `/etc/angie/` earlier,
copy them now:

```console
$ sudo rsync -a /etc/nginx/sites-available/ /etc/angie/sites-available/
```

Finally, recreate each symlink:

```console
$ sudo ln -s /etc/angie/sites-available/default \
             /etc/angie/sites-enabled/default
```



### Dynamic Modules

Find and [install](https://en.angie.software//angie/docs/installation/index.md#install-dynamicmodules)
Angie equivalents for all dynamic modules
referenced in nginx configuration, for example:

```console
$ sudo nginx -T | grep load_module

  load_module modules/ngx_http_geoip2_module.so;
  load_module modules/ngx_stream_geoip2_module.so;
  ...
```

This means you need to install the `angie-module-geoip2` package,
and so on.

There are two popular ways to include dynamic module configuration:

`/usr/share/nginx/modules/`

If dynamic modules are included via `/usr/share/nginx/modules/`,
update the path:

```nginx
# Load dynamic modules. See /usr/share/doc/nginx/README.dynamic.
# include /usr/share/nginx/modules/*.conf;

include /usr/share/angie/modules/*.conf;
```

Then copy the module configuration files:

```console
$ sudo rsync -a /usr/share/nginx/modules/ /usr/share/angie/modules/
```

Finally, change the [load_module](https://en.angie.software//angie/docs/configuration/modules/core.md#load-module) path in each file:

```nginx
# load_module "/usr/lib64/nginx/modules/ngx_http_geoip2_module.so";
load_module "/usr/lib64/angie/modules/ngx_http_geoip2_module.so";
```

`/etc/nginx/modules-enabled/`

If dynamic modules are included via
`/etc/nginx/modules-enabled/`,
update the path:

```nginx
# include /etc/nginx/modules-enabled/*.conf;
include /etc/angie/modules-enabled/*.conf;
```

Then recreate the symlinks in `/etc/angie/modules-enabled/`
to make everything work.

List the original module configuration files, for example:

```console
$ ls -l /etc/nginx/modules-enabled/

  mod-http-geoip2.conf -> /usr/share/nginx/modules-available/mod-http-geoip2.conf
```

Note their actual location;
here it's `/usr/share/nginx/modules-available/`.

Copy them to `/usr/share/angie/`:

```console
$ sudo rsync -a /usr/share/nginx/modules-available/ /usr/share/angie/modules-available/
```

Finally, recreate each symlink:

```console
$ sudo ln -s /usr/share/angie/modules-available/mod-http-geoip2.conf \
             /etc/angie/modules-enabled/mod-http-geoip2.conf
```



### Root Directory (Optional)

If [root](https://en.angie.software//angie/docs/configuration/modules/http/index.md#root) points to the
`/usr/share/nginx/html/` directory,
you can change the directive to point to Angie.

Copy the directory and update the `root` value in Angie configuration:

```console
$ sudo rsync -a /usr/share/nginx/html/ /usr/share/angie/html/
```

```nginx
# root /usr/share/nginx/html;
root /usr/share/angie/html;
```



### User and Group (Optional)

While it's sufficient to leave the [user](https://en.angie.software//angie/docs/configuration/modules/core.md#user) directive as is,
you can use Angie accounts for flexibility.

Update the `user` settings in Angie configuration:

```nginx
# user www-data www-data;
user angie angie;
```

Change the owner of *all* configuration files,
including files in `/usr/share/angie/`,
for example:

```console
$ sudo chown -R angie:angie /etc/angie/
$ sudo chown -R angie:angie /usr/share/angie/
```

If the Angie configuration has [root](https://en.angie.software//angie/docs/configuration/modules/http/index.md#root) directives,
change the owner of the directories specified there,
for example:

```console
$ sudo chown -R angie:angie /var/www/html/
```



### Wrapping Up

To make sure nothing is missed,
find and fix remaining mentions of `nginx` in Angie configuration:

```console
$ grep -rn --include='*.conf' 'nginx' /etc/angie/
```



## Testing and Switching

After updating Angie configuration,
the next step is to check its syntax
to ensure Angie can work with it,
and then switch over.
Verify that Angie accepts the new configuration:

```console
$ sudo angie -t
```

This command parses the configuration
and reports errors that would block Angie startup;
fix any issues and re-run the command.



### Stopping nginx, Starting Angie

To minimize downtime, start Angie immediately after stopping nginx:

```console
$ sudo systemctl stop nginx && sudo systemctl start angie
```

If needed, enable the Angie service to start after reboot:

```console
$ sudo systemctl enable angie
```

Migration complete! That's it; you're awesome.



### Disabling nginx

After confirming that Angie is running stably,
you can disable or remove nginx to avoid conflicts.

The minimum you can do is disable the service:

```console
$ sudo systemctl disable nginx
```



## Working with SSL Certificates

If you used Certbot to manage SSL certificates with nginx,
it will continue to work with Angie.



### Using Certbot with Angie

Supporting Angie in Certbot requires minimal effort,
since Angie is backward compatible with nginx.
For Certbot to work, it's sufficient to create a symlink
and specify the appropriate parameters:

```console
# Create a symlink for Certbot compatibility
$ sudo ln -s /etc/angie/angie.conf /etc/angie/nginx.conf

# Obtain a certificate for a domain
$ sudo certbot --nginx --nginx-server-root=/etc/angie --nginx-ctl=angie -d example.com -d www.example.com

# Automatically renew certificates
$ sudo certbot renew

# Check certificate status
$ sudo certbot certificates
```

After migrating to Angie, Certbot will continue to automatically renew certificates
through configured **cron** jobs or **systemd** timers.



### Migrating from Certbot to the Built-in ACME Module

Angie includes a built-in [ACME](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme) module,
which allows you to automatically obtain and renew SSL certificates
without using external tools like Certbot.

Advantages of the built-in ACME module:

- full integration with Angie configuration;
- automatic certificate renewal without additional services;
- support for HTTP and DNS validation;
- ability to obtain wildcard certificates.

For detailed instructions on migrating from Certbot to the built-in ACME module,
see the [Migrating from certbot](https://en.angie.software//angie/docs/configuration/acme.md#acme-config-certbot) section.



## Adapting Diverging Directives

A few nginx directives behave differently in Angie: some are renamed, some are
deprecated, and a couple are omitted entirely. If your configuration relies on
any of them, see [Unsupported nginx Directives](https://en.angie.software//angie/docs/configuration/nginx-unsupported-directives.md#nginx-unsupported-directives).

In particular, nginx's `keepalive_min_timeout` is named
[lingering_timeout](https://en.angie.software//angie/docs/configuration/modules/http/index.md#lingering-timeout) in Angie; rename it if it appears in your
configuration.



## Configuring Angie Features

It's safe to assume you're migrating for a reason.
Why not go further and configure some of the additional features
available in [Angie](https://en.angie.software//angie/docs/oss_changes.md#oss-changes) and [Angie PRO](https://en.angie.software//angie/docs/pro_changes.md#pro-changes)
that aren't in nginx?


# https://en.angie.software/angie/docs/configuration/nginx-unsupported-directives.md





# Unsupported nginx Directives

Most nginx directives work in Angie unchanged, so an existing configuration
usually needs no adjustment. This page lists the exceptions, the directives
that Angie removes, renames, or deprecates, so you can adapt your configuration
when moving from nginx.

Low-level tuning directives that nginx itself leaves undocumented, such as
event-method and gzip tuning knobs, keep working in Angie with their nginx
defaults and are intentionally omitted here.

#### NOTE
For the end-to-end migration process, see the
[migration guide](https://en.angie.software//angie/docs/configuration/migration.md#migration).

## Removed or Omitted

These nginx directives have no Angie equivalent.

| nginx directive                             | Notes                                                                                                                                                                                                                                                                                        |
|---------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `add_header_inherit`, `add_trailer_inherit` | Omitted because of their poor design; see [Angie Version History](https://en.angie.software//angie/docs/oss_changes.md#oss-changes).                                                                                                                                                         |
| `ssl_ech_file`                              | Omitted, along with the `$ssl_ech_status` and `$ssl_ech_outer_server_name` variables. Angie implements Encrypted Client Hello through the [ssl_encrypted_hello_key](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-encrypted-hello-key) directive instead. |

## Renamed

| nginx directive         | Angie directive                                                                                                  |
|-------------------------|------------------------------------------------------------------------------------------------------------------|
| `keepalive_min_timeout` | [lingering_timeout](https://en.angie.software//angie/docs/configuration/modules/http/index.md#lingering-timeout) |

## Deprecated

These directives still work but emit a warning; use the modern directive
instead.

| nginx directive                    | Use instead                                                                                                                          |
|------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|
| `http2_idle_timeout`               | [keepalive_timeout](https://en.angie.software//angie/docs/configuration/modules/http/index.md#keepalive-timeout)                     |
| `http2_max_requests`               | [keepalive_requests](https://en.angie.software//angie/docs/configuration/modules/http/index.md#keepalive-requests)                   |
| `http2_recv_timeout`               | [client_header_timeout](https://en.angie.software//angie/docs/configuration/modules/http/index.md#client-header-timeout)             |
| `http2_max_field_size`             | [large_client_header_buffers](https://en.angie.software//angie/docs/configuration/modules/http/index.md#large-client-header-buffers) |
| `http2_max_header_size`            | [large_client_header_buffers](https://en.angie.software//angie/docs/configuration/modules/http/index.md#large-client-header-buffers) |
| `proxy_downstream_buffer` (stream) | [proxy_buffer_size](https://en.angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-buffer-size)          |
| `proxy_upstream_buffer` (stream)   | [proxy_buffer_size](https://en.angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-buffer-size)          |


# https://en.angie.software/angie/docs/configuration/grafana.md





# Configuring the Grafana Dashboard

To configure the [dashboard for Angie](https://grafana.com/grafana/dashboards/20719-angie-dashboard/) in Grafana,
follow these steps:

1. Using the [Prometheus](https://en.angie.software//angie/docs/configuration/modules/http/http_prometheus.md#http-prometheus) module,
   add the following [include](https://en.angie.software//angie/docs/configuration/modules/core.md#include) directive in the `http` block
   of the [configuration file](https://en.angie.software//angie/docs/configuration/configfile.md#configfile):
   ```nginx
   http {
       include prometheus_all.conf;

       # ...
   }
   ```

   Also add the corresponding [prometheus](https://en.angie.software//angie/docs/configuration/modules/http/http_prometheus.md#id1) directive
   inside a `location` within a separate `server` block
   with a dedicated IP address and port for this purpose, for example:
   ```nginx
   server {

       listen 192.168.1.100:80;

       location =/p8s {
           prometheus all;
       }

       # ...

   }
   ```

   These enable the export of Angie metrics in Prometheus format
   at the endpoint specified in the `location`.
2. Add the following configuration to Prometheus,
   specifying the IP address and port set earlier in the `server`:
   ```yaml
   scrape_configs:
     - job_name: "angie"
       scrape_interval: 15s
       metrics_path: "/p8s"
       static_configs:
         - targets: ["192.168.1.100:80"]
   ```

   This will collect metrics every 15 seconds,
   using the `/p8s` path configured in the previous step.

   #### NOTE
   Make sure the global `scrape_interval` value
   does not exceed the value specified here.
3. Import the [dashboard for Angie](https://grafana.com/grafana/dashboards/20719-angie-dashboard/)
   into Grafana.


# https://en.angie.software/angie/docs/troubleshooting.md





# Troubleshooting

If you encounter a technical issue
and can't find a solution in other sections,
ask a question on the [community forum](https://forum.angie.support/)
or in the [Telegram channel](https://t.me/angie_support).

Technical support for clients:

- [https://support.angie.software](https://support.angie.software)
- [support@angie.software](mailto:support@angie.software)



## Debug Logging

The debug log should be enabled
before performing self-diagnostics or as recommended by technical support.

To do this, run Angie using the executable with debug support:

Linux

In the [pre-built packages](https://en.angie.software//angie/docs/installation/index.md#install-packages) for Linux,
the `angie-debug` file is built with debug logging enabled:

```console
$ ls -l /usr/sbin/ | grep angie

   lrwxrwxrwx 1 root root      13 Sep 21 18:58 angie -> angie-nodebug
   -rwxr-xr-x 1 root root 1561224 Sep 21 18:58 angie-debug
   -rwxr-xr-x 1 root root 1426056 Sep 21 18:58 angie-nodebug
```

Configure running `angie-debug`:

```console
$ sudo ln -fs angie-debug /usr/sbin/angie
$ sudo angie -t && sudo service angie upgrade
```

This will initiate a [live executable upgrade](https://en.angie.software//angie/docs/configuration/runtime.md#service-upgrade).

To revert to the regular executable after debugging:

```console
$ sudo ln -fs angie-nodebug /usr/sbin/angie
$ sudo angie -t && sudo service angie upgrade
```

FreeBSD

In the [pre-built packages](https://en.angie.software//angie/docs/installation/index.md#install-packages) for FreeBSD,
the `angie-debug` file is built with debug logging enabled:

```console
$ ls -l /usr/local/sbin/ | grep angie

   lrwxrwxrwx 1 root root      13 Sep 21 18:58 angie -> angie-nodebug
   -rwxr-xr-x 1 root root 1561224 Sep 21 18:58 angie-debug
   -rwxr-xr-x 1 root root 1426056 Sep 21 18:58 angie-nodebug
```

Configure running `angie-debug`:

```console
$ sudo ln -fs angie-debug /usr/local/sbin/angie
$ sudo angie -t && sudo service angie upgrade
```

This will initiate a [live executable upgrade](https://en.angie.software//angie/docs/configuration/runtime.md#service-upgrade).

To revert to the regular executable after debugging:

```console
$ sudo ln -fs angie-nodebug /usr/local/sbin/angie
$ sudo angie -t && sudo service angie upgrade
```

Docker

In [templated Docker images](https://en.angie.software//angie/docs/installation/docker.md#docker-images),
you can switch to the debug version
by overriding the `ANGIE_BINARY` environment variable:

```console
$ docker run -it --rm -e ANGIE_BINARY="angie-debug" \
  docker.angie.software/angie:templated
```

Building from Source

When building Angie from source,
[enable debugging](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure) before compilation:

```console
$ ./configure --with-debug ...
```

After installation, **angie -V** allows verifying
that debug logging is enabled:

```console
$ angie -V

  ...
  configure arguments: --with-debug ...
```

#### NOTE
Using the executable with debug support
may slightly reduce performance;
enabling the debug log can significantly reduce it
and increase disk space usage.

To enable the debug log,
set the `debug` level in the configuration
using the [error_log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log) directive:

```nginx
error_log /path/to/log debug;
```

And reload the configuration:

```console
$ sudo angie -t && sudo service angie reload
```

In [templated Docker images](https://en.angie.software//angie/docs/installation/docker.md#docker-images)
with debug logging enabled,
you can also use the `ANGIE_ERROR_LOG_SEVERITY`
environment variable:

```console
$ docker run -it --rm -e ANGIE_BINARY="angie-debug" \
-e ANGIE_ERROR_LOG_SEVERITY="debug" \
docker.angie.software/angie:templated
```

If you switch to the executable without debug support
but leave the `debug` level in the [error_log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log) directive,
Angie will log entries at the `info` level.

Overriding [error_log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log) in the configuration
without specifying the `debug` level disables the debug log.
Here, overriding the log at the [server](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server) level
disables debug logging for an individual server:

```nginx
error_log /path/to/log debug;

http {
   server {
     error_log /path/to/log;
    # ...
```

To avoid this, remove the line that overrides [error_log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log),
or set the `debug` level in it:

```nginx
error_log /path/to/log debug;

http {
   server {
     error_log /path/to/log debug;
   #  ...
```



### Directive Location

The location of the [error_log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log) directive
affects the completeness of debug information collected.

A directive specified at a lower configuration level
(for example, inside a `server` or `location` block)
overrides logging settings specified at a higher level
(for example, at the main configuration level or inside an `http` block).

### Debug log disabled for a specific server

If debug logging is enabled globally
but [error_log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log) is specified for an individual server without the `debug` level,
debug information will not be collected for that server.

```nginx
error_log /var/log/angie/error.log debug; # Global debug log

http {

    server {

        listen 80;
        server_name example.com;

        error_log /var/log/angie/example.com.error.log;
        # Debug log for example.com is disabled, file contains info level

        # ...
    }

    server {

        listen 80;
        server_name another.com;

        # This server will use the global debug log
        # ...
    }
}
```

### Preserving debug log at server level

To preserve debug information collection for a specific server
but direct it to a different file,
you must also specify the `debug` level:

```nginx
error_log /var/log/angie/error.log debug; # Global debug log

http {

    server {

        listen 80;
        server_name example.com;

        error_log /var/log/angie/example.com.error.log debug;
        # Debug log for example.com is enabled but written to a separate file

        # ...
    }
}
```

Therefore, to enable debug logging globally
but override the log file for individual blocks,
also specify the `debug` level in those overrides.
Otherwise, if no logging level is specified in the [error_log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log) directive,
the `error` level will be used by default
and debug information for those blocks will be lost.



### Logging Specific Addresses

You can enable debug logging only for
[specified client addresses](https://en.angie.software//angie/docs/configuration/modules/core.md#debug-connection):

```nginx
error_log /path/to/log;

events {
  debug_connection 192.168.1.1;
  debug_connection 192.168.10.0/24;
}
```



### Cyclic Memory Buffer

Debug log can be written to a cyclic memory buffer:

```nginx
error_log memory:32m debug;
```

Writing to the memory buffer at the `debug` level
will not significantly impact performance even under high load.
In this case, the log can be extracted using a GDB script, for example:

```console
set $log = ngx_cycle->log

while $log->writer != ngx_log_memory_writer
  set $log = $log->next
end

set $buf = (ngx_log_memory_buf_t *) $log->wdata
dump binary memory debug_log.txt $buf->start $buf->end
```



## Core Dumps

Core dumps help investigate crashes.
Include them when [contacting support](#troubleshooting).
For builds from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages),
we provide debug symbols in special packages.
They have the same names as the original packages
with the `-dbg` suffix added, for example `angie-dbg`.

#### NOTE
This section assumes
you are running Angie as the `root` user (recommended).



### Linux: systemd

To enable core dump saving when running Angie as a **systemd** service
(for example, when [installed from packages](https://en.angie.software//angie/docs/installation/index.md#install-packages)),
modify the [service settings](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#Process%20Properties)
in the `/lib/systemd/system/angie.service` file:

```ini
[Service]
...
LimitCORE=infinity
LimitNOFILE=65535
```

Or update the [global settings](https://www.freedesktop.org/software/systemd/man/systemd-system.conf.html)
in the `/etc/systemd/system.conf` file:

```ini
[Manager]
...
DefaultLimitCORE=infinity
DefaultLimitNOFILE=65535
```

Then reload the service configuration and restart Angie
to reproduce the crash conditions:

```console
$ sudo systemctl daemon-reload
$ sudo systemctl restart angie.service
```

After the crash, find the core dump file:

```console
$ sudo coredumpctl -1 # optional

   TIME                           PID   UID   GID SIG COREFILE  EXE
   --- 2026-07-17 11:05:40 GMT   1157     0     0  11 present   /usr/sbin/angie

$ sudo ls -al /var/lib/systemd/coredump/  # default, see also /etc/systemd/coredump.conf and /etc/systemd/coredump.conf.d/*.conf

  ...
  -rw-r----- 1 root root 177662 Jul 27 11:05 core.angie.0.6135489c850b4fb4a74795ebbc1e382a.1157.1590577472000000.lz4
```



### Linux: Manual Configuration

Check the [core dump settings](https://man7.org/linux/man-pages/man5/limits.conf.5.html)
in the `/etc/security/limits.conf` file, modify them if necessary:

```none
root soft core 0          # by default disables core dumps
root hard core unlimited  # allows increasing the size limit
```

Then increase the core dump size limit using [ulimit](https://man7.org/linux/man-pages/man1/ulimit.1p.html),
then restart Angie to reproduce the crash conditions:

```console
$ sudo ulimit -c unlimited
$ sudo cd 
$ sudo sbin/angie  # or sbin/angie-debug
```

After the crash, find the core dump file:

```console
$ sudo ls -al   # default, see /proc/sys/kernel/core_pattern
  ...
  -rw-r----- 1 root root 177662 Jul 27 11:05 core.1157
```



### FreeBSD

Check the [core dump settings](https://man.freebsd.org/cgi/man.cgi?query=sysctl.conf&sektion=5)
in the `/etc/sysctl.conf` file, modify them if necessary:

```ini
kern.coredump=1                             # should be 1
kern.corefile=/path/to/core/files/%N.core   # needs correct path
```

Or update the settings at runtime:

```console
$ sudo sysctl kern.coredump=1
$ sudo sysctl kern.corefile=/path/to/core/files/%N.core
```

Then restart Angie to reproduce the crash conditions.
If Angie is installed as a service:

```console
$ sudo service angie restart
```

If Angie is installed manually:

```console
$ sudo cd 
$ sudo sbin/angie
```

After the crash, find the core dump file:

```console
$ sudo ls -al 

  ...
  -rw------- 1 root root 9912320 Jul 27 11:05 angie.core
```


# https://en.angie.software/angie/docs/development.md





# Development

Angie is an open-source project
that welcomes all contributors.



## Source Code

You can clone Angie source code from our public repositories:
[Mercurial](https://hg.angie.software/angie),
[Git](https://git.angie.software/web-server/angie).



## Coding Style

Your changes should be consistent with the rest of Angie's code;
the [coding conventions](https://en.angie.software//angie/docs/developer_guide.md#developer-guide) are a good starting point.



### Commit Messages

Historically, the commit log is maintained in English.

Start with a one-line summary of what was done.
It may have a prefix that the commit log uses for the affected code portion.
The summary can be up to 67 characters long
and may be followed by a blank line and more details.

A good message tells what caused the change, what was done about it,
and what the situation is now:

```none
API: bad things removed, good things added.

As explained elsewhere[1], the original API was bad because stuff;
this change was introduced to improve that aspect locally.

Levels of goodness have been implemented to mitigate the badness;
this is now the preferred way to work.  Also, the badness is gone.

[1] https://example.com
```

Details that may otherwise go unnoticed:

- Summary ends with a period and starts with a capital letter.
- If a prefix is used, it is followed by a lowercase letter.
- Double whitespace separates sentences within a single line.



## Final Checks

- Do your best to verify that the changes work on *all* target platforms.
- For each platform, run the test suite to make sure there's no regression:
  ```sh
  $ cd tests
  $ prove .
  ```

  See the `tests/README` file for details.
- Make sure you're comfortable with the [legal terms](https://en.angie.software//legal/index.md#legal).



## Submitting Contributions

To submit a patch, create a pull request on our
[GitHub mirror](https://github.com/webserver-llc/angie/).

For questions and suggestions, please contact the developers via
[GitHub Issues](https://github.com/webserver-llc/angie/issues).


# https://en.angie.software/angie/docs/developer_guide.md





# Developer Guide



## Coding conventions

The source code follows the following structure and conventions.



### Code layout

* `auto` — Build scripts
* `src`
  * `core` — Basic types and functions — string, array, log,
    pool, etc.
  * `event` — Event core
    * `modules` — Event notification modules:
      `epoll`, `kqueue`, `select`
      etc.
  * `http` — Core HTTP module and common code
    * `modules` — Other HTTP modules
    * `v2` — HTTP/2
  * `mail` — Mail modules
  * `os` — Platform-specific code
    * `unix`
    * `win32`
  * `stream` — Stream modules



### Include files

The following two `#include` statements must appear at the
beginning of every Angie file:

```c
#include 
#include 
```

In addition to that, HTTP code should include

```c
#include 
```

Mail code should include

```c
#include 
```

Stream code should include

```c
#include 
```



### Integers

For general purposes, Angie code uses two integer types,
`ngx_int_t` and `ngx_uint_t`, which are
typedefs for `intptr_t` and `uintptr_t`
respectively.



### Common return codes

Most functions in Angie return the following codes:

* `NGX_OK` — Operation succeeded.
* `NGX_ERROR` — Operation failed.
* `NGX_AGAIN` — Operation incomplete; call the function again.
* `NGX_DECLINED` — Operation rejected, for example, because it is
  disabled in the configuration. This is never an error.
* `NGX_BUSY` — Resource is not available.
* `NGX_DONE` — Operation complete or continued elsewhere.
  Also used as an alternative success code.
* `NGX_ABORT` — Function was aborted.
  Also used as an alternative error code.



### Error handling

The `ngx_errno` macro returns the last system error code.
It's mapped to `errno` on POSIX platforms and to a
`GetLastError()` call in Windows.
The `ngx_socket_errno` macro returns the last socket error
number.
Like the `ngx_errno` macro, it's mapped to
`errno` on POSIX platforms.
It's mapped to a `WSAGetLastError()` call in Windows.
Accessing the values of `ngx_errno` or
`ngx_socket_errno` more than once in a row can cause
performance issues.
If the error value might be used multiple times, store it in a local variable
of type `ngx_err_t`.
To set errors, use the `ngx_set_errno(errno)` and
`ngx_set_socket_errno(errno)` macros.

The values of `ngx_errno` and
`ngx_socket_errno` can be passed to the logging functions
`ngx_log_error()` and `ngx_log_debugX()`, in
which case system error text is added to the log message.

Example using `ngx_errno`:

```c
ngx_int_t
ngx_my_kill(ngx_pid_t pid, ngx_log_t *log, int signo)
{
    ngx_err_t  err;

    if (kill(pid, signo) == -1) {
        err = ngx_errno;

        ngx_log_error(NGX_LOG_ALERT, log, err, "kill(%P, %d) failed", pid, signo);

        if (err == NGX_ESRCH) {
            return 2;
        }

        return 1;
    }

    return 0;
}
```



### Strings



#### Overview

For C strings, Angie uses the unsigned character type pointer
`u_char *`.

The Angie string type `ngx_str_t` is defined as follows:

```c
typedef struct {
    size_t      len;
    u_char     *data;
} ngx_str_t;
```

The `len` field holds the string length and
`data` holds the string data.
The string, held in `ngx_str_t`, may or may not be
null-terminated after the `len` bytes.
In most cases it's not.
However, in certain parts of the code (for example, when parsing configuration),
`ngx_str_t` objects are known to be null-terminated, which
simplifies string comparison and makes it easier to pass the strings to
syscalls.

The string operations in Angie are declared in
`src/core/ngx_string.h`.
Some of them are wrappers around standard C functions:

* `ngx_strcmp()`
* `ngx_strncmp()`
* `ngx_strstr()`
* `ngx_strlen()`
* `ngx_strchr()`
* `ngx_memcmp()`
* `ngx_memset()`
* `ngx_memcpy()`
* `ngx_memmove()`

Other string functions are Angie-specific:

* `ngx_memzero()` — Fills memory with zeroes.
* `ngx_explicit_memzero()` — Does the same as
  `ngx_memzero()`, but this call is never removed by the
  compiler's dead store elimination optimization.
  This function can be used to clear sensitive data such as passwords and keys.
* `ngx_cpymem()` — Does the same as
  `ngx_memcpy()`, but returns the final destination address.
  This one is handy for appending multiple strings in a row.
* `ngx_movemem()` — Does the same as
  `ngx_memmove()`, but returns the final destination address.
* `ngx_strlchr()` — Searches for a character in a string,
  delimited by two pointers.

The following functions perform case conversion and comparison:

* `ngx_tolower()`
* `ngx_toupper()`
* `ngx_strlow()`
* `ngx_strcasecmp()`
* `ngx_strncasecmp()`

The following macros simplify string initialization:

* `ngx_string(text)` — static initializer for the
  `ngx_str_t` type from the C string literal
  `text`
* `ngx_null_string` — static empty string initializer for the
  `ngx_str_t` type
* `ngx_str_set(str, text)` — initializes string
  `str` of `ngx_str_t *` type with the C string
  literal `text`
* `ngx_str_null(str)` — initializes string `str`
  of `ngx_str_t *` type with the empty string



#### Formatting

The following formatting functions support Angie-specific types:

* `ngx_sprintf(buf, fmt, ...)`
* `ngx_snprintf(buf, max, fmt, ...)`
* `ngx_slprintf(buf, last, fmt, ...)`
* `ngx_vslprintf(buf, last, fmt, args)`
* `ngx_vsnprintf(buf, max, fmt, args)`

The full list of formatting options supported by these functions is
in `src/core/ngx_string.c`. Some of them are:

* `%O` — `off_t`
* `%T` — `time_t`
* `%z` — `ssize_t`
* `%i` — `ngx_int_t`
* `%p` — `void *`
* `%V` — `ngx_str_t *`
* `%s` — `u_char *` (null-terminated)
* `%*s` — `size_t + u_char *`

You can prepend `u` on most types to make them unsigned.
To convert output to hex, use `X` or `x`.



### Numeric conversion

Several functions for numeric conversion are implemented in Angie.
The first four each convert a string of given length to a positive integer of
the indicated type.
They return `NGX_ERROR` on error.

* `ngx_atoi(line, n)` — `ngx_int_t`
* `ngx_atosz(line, n)` — `ssize_t`
* `ngx_atoof(line, n)` — `off_t`
* `ngx_atotm(line, n)` — `time_t`

There are two additional numeric conversion functions.
Like the first four, they return `NGX_ERROR` on error.

* `ngx_atofp(line, n, point)` — Converts a fixed point number
  of given length to a positive integer of type
  `ngx_int_t`.
  The result is shifted left by `point` decimal
  positions.
  The string representation of the number is expected to have no more
  than `point` fractional digits.
  For example, `ngx_atofp("10.5", 4, 2)` returns
  `1050`.
* `ngx_hextoi(line, n)` — Converts a hexadecimal representation
  of a positive integer to `ngx_int_t`.



### Regular expressions

The regular expressions interface in Angie is a wrapper around
the [PCRE](http://www.pcre.org) library.
The corresponding header file is `src/core/ngx_regex.h`.

To use a regular expression for string matching, it first needs to be
compiled, which is usually done at the configuration phase.
Note that since PCRE support is optional, all code using the interface must
be protected by the surrounding `NGX_PCRE` macro:

```c
#if (NGX_PCRE)
ngx_regex_t          *re;
ngx_regex_compile_t   rc;

u_char                errstr[NGX_MAX_CONF_ERRSTR];

ngx_str_t  value = ngx_string("message (\\d\\d\\d).*Codeword is '(?\\w+)'");

ngx_memzero(&rc, sizeof(ngx_regex_compile_t));

rc.pattern = value;
rc.pool = cf->pool;
rc.err.len = NGX_MAX_CONF_ERRSTR;
rc.err.data = errstr;
/* rc.options can be set to NGX_REGEX_CASELESS */

if (ngx_regex_compile(&rc) != NGX_OK) {
    ngx_conf_log_error(NGX_LOG_EMERG, cf, 0, "%V", &rc.err);
    return NGX_CONF_ERROR;
}

re = rc.regex;
#endif
```

After successful compilation, the `captures` and
`named_captures` fields in the
`ngx_regex_compile_t` structure contain the count of all
captures and named captures, respectively, found in the regular expression.

The compiled regular expression can then be used for matching against strings:

```c
ngx_int_t  n;
int        captures[(1 + rc.captures) * 3];

ngx_str_t input = ngx_string("This is message 123. Codeword is 'foobar'.");

n = ngx_regex_exec(re, &input, captures, (1 + rc.captures) * 3);
if (n >= 0) {
    /* string matches expression */

} else if (n == NGX_REGEX_NO_MATCHED) {
    /* no match was found */

} else {
    /* some error */
    ngx_log_error(NGX_LOG_ALERT, log, 0, ngx_regex_exec_n " failed: %i", n);
}
```

The arguments to `ngx_regex_exec()` are the compiled regular
expression `re`, the string to match `input`,
an optional array of integers to hold any `captures` that are
found, and the array's `size`.
The size of the `captures` array must be a multiple of three,
as required by the
[PCRE API](http://www.pcre.org/original/doc/html/pcreapi.html).
In the example, the size is calculated from the total number of captures plus
one for the matched string itself.

If there are matches, captures can be accessed as follows:

```c
u_char     *p;
size_t      size;
ngx_str_t   name, value;

/* all captures */
for (i = 0; i < n * 2; i += 2) {
    value.data = input.data + captures[i];
    value.len = captures[i + 1] - captures[i];
}

/* accessing named captures */

size = rc.name_size;
p = rc.names;

for (i = 0; i < rc.named_captures; i++, p += size) {

    /* capture name */
    name.data = &p[2];
    name.len = ngx_strlen(name.data);

    n = 2 * ((p[0] << 8) + p[1]);

    /* captured value */
    value.data = &input.data[captures[n]];
    value.len = captures[n + 1] - captures[n];
}
```

The `ngx_regex_exec_array()` function accepts an array of
`ngx_regex_elt_t` elements (which are just compiled regular
expressions with associated names), a string to match, and a log.
The function applies expressions from the array to the string until
either a match is found or no more expressions are left.
The return value is `NGX_OK` when there is a match and
`NGX_DECLINED` otherwise, or `NGX_ERROR`
in case of error.



### Time

The `ngx_time_t` structure represents time with three separate
types for seconds, milliseconds, and the GMT offset:

```c
typedef struct {
    time_t      sec;
    ngx_uint_t  msec;
    ngx_int_t   gmtoff;
} ngx_time_t;
```

The `ngx_tm_t` structure is an alias for
`struct tm` on UNIX platforms and `SYSTEMTIME`
on Windows.

To obtain the current time, it is usually sufficient to access one of the
available global variables, representing the cached time value in the desired
format.

The available string representations are:

* `ngx_cached_err_log_time` — Used in error log entries:
  `"1970/09/28 12:00:00"`
* `ngx_cached_http_log_time` — Used in HTTP access log entries:
  `"28/Sep/1970:12:00:00 +0600"`
* `ngx_cached_syslog_time` — Used in syslog entries:
  `"Sep 28 12:00:00"`
* `ngx_cached_http_time` — Used in HTTP headers:
  `"Mon, 28 Sep 1970 06:00:00 GMT"`
* `ngx_cached_http_log_iso8601` — The ISO 8601 standard format:
  `"1970-09-28T12:00:00+06:00"`

The `ngx_time()` and `ngx_timeofday()` macros
return the current time value in seconds and are the preferred way to access
the cached time value.

To obtain the time explicitly, use `ngx_gettimeofday()`,
which updates its argument (pointer to
`struct timeval`).
The time is always updated when Angie returns to the event loop from system
calls.
To update the time immediately, call `ngx_time_update()`,
or `ngx_time_sigsafe_update()` if updating the time in the
signal handler context.

The following functions convert `time_t` into the indicated
broken-down time representation.
The first function in each pair converts `time_t` to
`ngx_tm_t` and the second (with the `_libc_`
infix) to `struct tm`:

* `ngx_gmtime(), ngx_libc_gmtime()` — Time expressed as UTC
* `ngx_localtime(), ngx_libc_localtime()` — Time expressed
  relative to the local time zone

The `ngx_http_time(buf, time)` function returns a string
representation suitable for use in HTTP headers (for example,
`"Mon, 28 Sep 1970 06:00:00 GMT"`).
The `ngx_http_cookie_time(buf, time)` function returns a string
representation suitable for HTTP cookies (`"Thu, 31-Dec-37 23:55:55 GMT"`).



## Containers



### Array

The Angie array type `ngx_array_t` is defined as follows

```c
typedef struct {
    void        *elts;
    ngx_uint_t   nelts;
    size_t       size;
    ngx_uint_t   nalloc;
    ngx_pool_t  *pool;
} ngx_array_t;
```

The elements of the array are available in the `elts` field.
The `nelts` field holds the number of elements.
The `size` field holds the size of a single element and is set
when the array is initialized.

Use the `ngx_array_create(pool, n, size)` call to create an
array in a pool, and the `ngx_array_init(array, pool, n, size)`
call to initialize an array object that has already been allocated.

```c
ngx_array_t  *a, b;

/* create an array of strings with preallocated memory for 10 elements */
a = ngx_array_create(pool, 10, sizeof(ngx_str_t));

/* initialize string array for 10 elements */
ngx_array_init(&b, pool, 10, sizeof(ngx_str_t));
```

Use the following functions to add elements to an array:

* `ngx_array_push(a)` adds one tail element and returns a pointer
  to it
* `ngx_array_push_n(a, n)` adds `n` tail elements
  and returns a pointer to the first one

If the currently allocated amount of memory is not large enough to accommodate
the new elements, a new block of memory is allocated and the existing elements
are copied to it.
The new memory block is normally twice as large as the existing one.

```c
s = ngx_array_push(a);
ss = ngx_array_push_n(&b, 3);
```



### List

In Angie a list is a sequence of arrays, optimized for inserting a potentially
large number of items.
The `ngx_list_t` list type is defined as follows:

```c
typedef struct {
    ngx_list_part_t  *last;
    ngx_list_part_t   part;
    size_t            size;
    ngx_uint_t        nalloc;
    ngx_pool_t       *pool;
} ngx_list_t;
```

The actual items are stored in list parts, which are defined as follows:

```c
typedef struct ngx_list_part_s  ngx_list_part_t;

struct ngx_list_part_s {
    void             *elts;
    ngx_uint_t        nelts;
    ngx_list_part_t  *next;
};
```

Before use, a list must be initialized by calling
`ngx_list_init(list, pool, n, size)` or created by calling
`ngx_list_create(pool, n, size)`.
Both functions take as arguments the size of a single item and a number of
items per list part.
To add an item to a list, use the `ngx_list_push(list)` function.
To iterate over the items, directly access the list fields as shown in the
example:

```c
ngx_str_t        *v;
ngx_uint_t        i;
ngx_list_t       *list;
ngx_list_part_t  *part;

list = ngx_list_create(pool, 100, sizeof(ngx_str_t));
if (list == NULL) { /* error */ }

/* add items to the list */

v = ngx_list_push(list);
if (v == NULL) { /* error */ }
ngx_str_set(v, "foo");

v = ngx_list_push(list);
if (v == NULL) { /* error */ }
ngx_str_set(v, "bar");

/* iterate over the list */

part = &list->part;
v = part->elts;

for (i = 0; /* void */; i++) {

    if (i >= part->nelts) {
        if (part->next == NULL) {
            break;
        }

        part = part->next;
        v = part->elts;
        i = 0;
    }

    ngx_do_smth(&v[i]);
}
```

Lists are primarily used for HTTP input and output headers.

Lists do not support item removal.
However, when needed, items can internally be marked as missing without actually
being removed from the list.
For example, to mark HTTP output headers (which are stored as
`ngx_table_elt_t` objects) as missing, set the
`hash` field in `ngx_table_elt_t` to
zero.
Items marked in this way are explicitly skipped when the headers are iterated
over.



### Queue

In Angie a queue is an intrusive doubly linked list, with each node defined as
follows:

```c
typedef struct ngx_queue_s  ngx_queue_t;

struct ngx_queue_s {
    ngx_queue_t  *prev;
    ngx_queue_t  *next;
};
```

The head queue node is not linked with any data.
Use the `ngx_queue_init(q)` call to initialize the list head
before use.
Queues support the following operations:

* `ngx_queue_insert_head(h, x)`,
  `ngx_queue_insert_tail(h, x)` — Insert a new node
* `ngx_queue_remove(x)` — Remove a queue node
* `ngx_queue_split(h, q, n)` — Split a queue at a node,
  returning the queue tail in a separate queue
* `ngx_queue_add(h, n)` — Add a second queue to the first queue
* `ngx_queue_head(h)`,
  `ngx_queue_last(h)` — Get first or last queue node
* `ngx_queue_sentinel(h)` — Get a queue sentinel object to end
  iteration at
* `ngx_queue_data(q, type, link)` — Get a reference to the
  beginning of a queue node data structure, considering the queue field offset in
  it

An example:

```c
typedef struct {
    ngx_str_t    value;
    ngx_queue_t  queue;
} ngx_foo_t;

ngx_foo_t    *f;
ngx_queue_t   values, *q;

ngx_queue_init(&values);

f = ngx_palloc(pool, sizeof(ngx_foo_t));
if (f == NULL) { /* error */ }
ngx_str_set(&f->value, "foo");

ngx_queue_insert_tail(&values, &f->queue);

/* insert more nodes here */

for (q = ngx_queue_head(&values);
     q != ngx_queue_sentinel(&values);
     q = ngx_queue_next(q))
{
    f = ngx_queue_data(q, ngx_foo_t, queue);

    ngx_do_smth(&f->value);
}
```



### Red-Black tree

The `src/core/ngx_rbtree.h` header file provides access to the
effective implementation of red-black trees.

```c
typedef struct {
    ngx_rbtree_t       rbtree;
    ngx_rbtree_node_t  sentinel;

    /* custom per-tree data here */
} my_tree_t;

typedef struct {
    ngx_rbtree_node_t  rbnode;

    /* custom per-node data */
    foo_t              val;
} my_node_t;
```

To deal with a tree as a whole, you need two nodes: root and sentinel.
Typically, they are added to a custom structure, allowing you to
organize your data into a tree in which the leaves contain a link to or embed
your data.

To initialize a tree:

```c
my_tree_t  root;

ngx_rbtree_init(&root.rbtree, &root.sentinel, insert_value_function);
```

To traverse a tree and insert new values, use the
"`insert_value`" functions.
For example, the `ngx_str_rbtree_insert_value` function deals
with the `ngx_str_t` type.
Its arguments are pointers to a root node of an insertion, the newly created
node to be added, and a tree sentinel.

```c
void ngx_str_rbtree_insert_value(ngx_rbtree_node_t *temp,
                                 ngx_rbtree_node_t *node,
                                 ngx_rbtree_node_t *sentinel)
```

The traversal is pretty straightforward and can be demonstrated with the
following lookup function pattern:

```c
my_node_t *
my_rbtree_lookup(ngx_rbtree_t *rbtree, foo_t *val, uint32_t hash)
{
    ngx_int_t           rc;
    my_node_t          *n;
    ngx_rbtree_node_t  *node, *sentinel;

    node = rbtree->root;
    sentinel = rbtree->sentinel;

    while (node != sentinel) {

        n = (my_node_t *) node;

        if (hash != node->key) {
            node = (hash < node->key) ? node->left : node->right;
            continue;
        }

        rc = compare(val, node->val);

        if (rc < 0) {
            node = node->left;
            continue;
        }

        if (rc > 0) {
            node = node->right;
            continue;
        }

        return n;
    }

    return NULL;
}
```

The `compare()` function is a classic comparator function that
returns a value less than, equal to, or greater than zero.
To speed up lookups and avoid comparing user objects that can be big, an integer
hash field is used.

To add a node to a tree, allocate a new node, initialize it and call
`ngx_rbtree_insert()`:

```c
my_node_t          *my_node;
ngx_rbtree_node_t  *node;

my_node = ngx_palloc(...);
init_custom_data(&my_node->val);

node = &my_node->rbnode;
node->key = create_key(my_node->val);

ngx_rbtree_insert(&root->rbtree, node);
```

To remove a node, call the `ngx_rbtree_delete()` function:

```c
ngx_rbtree_delete(&root->rbtree, node);
```



### Hash

Hash table functions are declared in `src/core/ngx_hash.h`.
Both exact and wildcard matching are supported.
The latter requires extra setup and is described in a separate section below.

Before initializing a hash, you need to know the number of elements it will
hold so that Angie can build it optimally.
Two parameters that need to be configured are `max_size`
and `bucket_size`, as detailed in a separate
[document](https://en.angie.software//angie/docs/configuration/configfile.md#configure-hashes).
They are usually configurable by the user.
Hash initialization settings are stored with the
`ngx_hash_init_t` type, and the hash itself is
`ngx_hash_t`:

```c
ngx_hash_t       foo_hash;
ngx_hash_init_t  hash;

hash.hash = &foo_hash;
hash.key = ngx_hash_key;
hash.max_size = 512;
hash.bucket_size = ngx_align(64, ngx_cacheline_size);
hash.name = "foo_hash";
hash.pool = cf->pool;
hash.temp_pool = cf->temp_pool;
```

The `key` is a pointer to a function that creates the hash
integer key from a string.
There are two generic key-creation functions:
`ngx_hash_key(data, len)` and
`ngx_hash_key_lc(data, len)`.
The latter converts a string to all lowercase characters, so the passed string
must be writable.
If that is not true, pass the `NGX_HASH_READONLY_KEY` flag
to the function, initializing the key array (see below).

The hash keys are stored in `ngx_hash_keys_arrays_t` and
are initialized with `ngx_hash_keys_array_init(arr, type)`:
The second parameter (`type`) controls the amount of resources
preallocated for the hash and can be either `NGX_HASH_SMALL` or
`NGX_HASH_LARGE`.
The latter is appropriate if you expect the hash to contain thousands of
elements.

```c
ngx_hash_keys_arrays_t  foo_keys;

foo_keys.pool = cf->pool;
foo_keys.temp_pool = cf->temp_pool;

ngx_hash_keys_array_init(&foo_keys, NGX_HASH_SMALL);
```

To insert keys into a hash keys array, use the
`ngx_hash_add_key(keys_array, key, value, flags)` function:

```c
ngx_str_t k1 = ngx_string("key1");
ngx_str_t k2 = ngx_string("key2");

ngx_hash_add_key(&foo_keys, &k1, &my_data_ptr_1, NGX_HASH_READONLY_KEY);
ngx_hash_add_key(&foo_keys, &k2, &my_data_ptr_2, NGX_HASH_READONLY_KEY);
```

To build the hash table, call the
`ngx_hash_init(hinit, key_names, nelts)` function:

```c
ngx_hash_init(&hash, foo_keys.keys.elts, foo_keys.keys.nelts);
```

The function fails if `max_size` or
`bucket_size` parameters are not big enough.

When the hash is built, use the
`ngx_hash_find(hash, key, name, len)` function to look up
elements:

```c
my_data_t   *data;
ngx_uint_t   key;

key = ngx_hash_key(k1.data, k1.len);

data = ngx_hash_find(&foo_hash, key, k1.data, k1.len);
if (data == NULL) {
    /* key not found */
}
```



#### Wildcard matching

To create a hash that works with wildcards, use the
`ngx_hash_combined_t` type.
It includes the hash type described above and has two additional keys arrays:
`dns_wc_head` and `dns_wc_tail`.
The initialization of basic properties is similar to a regular hash:

```c
ngx_hash_init_t      hash
ngx_hash_combined_t  foo_hash;

hash.hash = &foo_hash.hash;
hash.key = ...;
```

It is possible to add wildcard keys using the
`NGX_HASH_WILDCARD_KEY` flag:

```c
/* k1 = ".example.org"; */
/* k2 = "foo.*";        */
ngx_hash_add_key(&foo_keys, &k1, &data1, NGX_HASH_WILDCARD_KEY);
ngx_hash_add_key(&foo_keys, &k2, &data2, NGX_HASH_WILDCARD_KEY);
```

The function recognizes wildcards and adds keys into the corresponding arrays.
Please refer to the
[Map](https://en.angie.software//angie/docs/configuration/modules/http/http_map.md#http-map) module
documentation for the description of the wildcard syntax and the
matching algorithm.

Depending on the contents of added keys, you may need to initialize up to three
key arrays: one for exact matching (described above), and two more to enable
matching starting from the head or tail of a string:

```c
if (foo_keys.dns_wc_head.nelts) {

    ngx_qsort(foo_keys.dns_wc_head.elts,
              (size_t) foo_keys.dns_wc_head.nelts,
              sizeof(ngx_hash_key_t),
              cmp_dns_wildcards);

    hash.hash = NULL;
    hash.temp_pool = pool;

    if (ngx_hash_wildcard_init(&hash, foo_keys.dns_wc_head.elts,
                               foo_keys.dns_wc_head.nelts)
        != NGX_OK)
    {
        return NGX_ERROR;
    }

    foo_hash.wc_head = (ngx_hash_wildcard_t *) hash.hash;
}
```

The keys array needs to be sorted, and initialization results must be added
to the combined hash.
The initialization of `dns_wc_tail` array is done similarly.

The lookup in a combined hash is handled by the
`ngx_hash_find_combined(chash, key, name, len)`:

```c
/* key = "bar.example.org"; - will match ".example.org" */
/* key = "foo.example.com"; - will match "foo.*"        */

hkey = ngx_hash_key(key.data, key.len);
res = ngx_hash_find_combined(&foo_hash, hkey, key.data, key.len);
```



## Memory management



### Heap

To allocate memory from system heap, use the following functions:

* `ngx_alloc(size, log)` — Allocate memory from system heap.
  This is a wrapper around `malloc()` with logging support.
  Allocation error and debugging information is logged to `log`.
* `ngx_calloc(size, log)` — Allocate memory from system heap
  like `ngx_alloc()`, but fill memory with zeros after
  allocation.
* `ngx_memalign(alignment, size, log)` — Allocate aligned memory
  from system heap.
  This is a wrapper around `posix_memalign()`
  on those platforms that provide that function.
  Otherwise implementation falls back to `ngx_alloc()` which
  provides maximum alignment.
* `ngx_free(p)` — Free allocated memory.
  This is a wrapper around `free()`.



### Pooling

Most Angie allocations are done in pools.
Memory allocated in an Angie pool is freed automatically when the pool is
destroyed.
This provides good allocation performance and makes memory control easy.

A pool internally allocates objects in continuous blocks of memory.
Once a block is full, a new one is allocated and added to the pool memory
block list.
When the requested allocation is too large to fit into a block, the request
is forwarded to the system allocator and the
returned pointer is stored in the pool for further deallocation.

The type for Angie pools is `ngx_pool_t`.
The following operations are supported:

* `ngx_create_pool(size, log)` — Create a pool with specified
  block size.
  The pool object returned is allocated in the pool as well.
  The `size`
  should be at least `NGX_MIN_POOL_SIZE`
  and a multiple of `NGX_POOL_ALIGNMENT`.
* `ngx_destroy_pool(pool)` — Free all pool memory, including
  the pool object itself.
* `ngx_palloc(pool, size)` — Allocate aligned memory from the
  specified pool.
* `ngx_pcalloc(pool, size)` — Allocate aligned memory
  from the specified pool and fill it with zeroes.
* `ngx_pnalloc(pool, size)` — Allocate unaligned memory from the
  specified pool.
  Mostly used for allocating strings.
* `ngx_pfree(pool, p)` — Free memory that was previously
  allocated in the specified pool.
  Only allocations that result from requests forwarded to the system allocator
  can be freed.

```c
u_char      *p;
ngx_str_t   *s;
ngx_pool_t  *pool;

pool = ngx_create_pool(1024, log);
if (pool == NULL) { /* error */ }

s = ngx_palloc(pool, sizeof(ngx_str_t));
if (s == NULL) { /* error */ }
ngx_str_set(s, "foo");

p = ngx_pnalloc(pool, 3);
if (p == NULL) { /* error */ }
ngx_memcpy(p, "foo", 3);
```

Chain links (`ngx_chain_t`) are actively used in Angie,
so the Angie pool implementation provides a way to reuse them.
The `chain` field of `ngx_pool_t` keeps a
list of previously allocated links ready for reuse.
For efficient allocation of a chain link in a pool, use the
`ngx_alloc_chain_link(pool)` function.
This function looks up a free chain link in the pool list and allocates a new
chain link if the pool list is empty.
To free a link, call the `ngx_free_chain(pool, cl)` function.

Cleanup handlers can be registered in a pool.
A cleanup handler is a callback with an argument which is called when the pool is
destroyed.
A pool is usually tied to a specific Angie object (like an HTTP request) and is
destroyed when the object reaches the end of its lifetime.
Registering a pool cleanup is a convenient way to release resources, close
file descriptors or make final adjustments to the shared data associated with
the main object.

To register a pool cleanup, call
`ngx_pool_cleanup_add(pool, size)`, which returns a
`ngx_pool_cleanup_t` pointer to
be filled in by the caller.
Use the `size` argument to allocate context for the cleanup
handler.

```c
ngx_pool_cleanup_t  *cln;

cln = ngx_pool_cleanup_add(pool, 0);
if (cln == NULL) { /* error */ }

cln->handler = ngx_my_cleanup;
cln->data = "foo";

...

static void
ngx_my_cleanup(void *data)
{
    u_char  *msg = data;

    ngx_do_smth(msg);
}
```



### Shared memory

Shared memory is used by Angie to share common data between processes.
The `ngx_shared_memory_add(cf, name, size, tag)` function adds
a new shared memory entry `ngx_shm_zone_t` to a cycle.
The function receives the `name` and `size`
of the zone.
Each shared zone must have a unique name.
If a shared zone entry with the provided `name` and
`tag` already exists, the existing zone entry is reused.
The function fails with an error if an existing entry with the same name has a
different tag.
Usually, the address of the module structure is passed as
`tag`, making it possible to reuse shared zones by name within
one Angie module.

The shared memory entry structure `ngx_shm_zone_t` has the
following fields:

* `init` — Initialization callback, called after the shared zone
  is mapped to actual memory
* `data` — Data context, used to pass arbitrary data to the
  `init` callback
* `noreuse` — Flag that disables reuse of a shared zone from the
  old cycle
* `tag` — Shared zone tag
* `shm` — Platform-specific object of type
  `ngx_shm_t`, having at least the following fields:
  * `addr` — Mapped shared memory address, initially NULL
  * `size` — Shared memory size
  * `name` — Shared memory name
  * `log` — Shared memory log
  * `exists` — Flag that indicates shared memory was inherited
    from the master process (Windows-specific)

Shared zone entries are mapped to actual memory in
`ngx_init_cycle()` after the configuration is parsed.
On POSIX systems, the `mmap()` syscall is used to create the
shared anonymous mapping.
On Windows, the `CreateFileMapping()`/
`MapViewOfFileEx()` pair is used.

For allocating in shared memory, Angie provides the slab pool
`ngx_slab_pool_t` type.
A slab pool for allocating memory is automatically created in each Angie shared
zone.
The pool is located in the beginning of the shared zone and can be accessed by
the expression `(ngx_slab_pool_t *) shm_zone->shm.addr`.
To allocate memory in a shared zone, call either
`ngx_slab_alloc(pool, size)` or
`ngx_slab_calloc(pool, size)`.
To free memory, call `ngx_slab_free(pool, p)`.

The slab pool divides all shared zone into pages.
Each page is used for allocating objects of the same size.
The specified size must be a power of 2, and greater than the minimum size of
8 bytes.
Nonconforming values are rounded up.
A bitmask for each page tracks which blocks are in use and which are free for
allocation.
For sizes greater than a half page (which is usually 2048 bytes), allocation is
done an entire page at a time.

To protect data in shared memory from concurrent access, use the mutex
available in the `mutex` field of
`ngx_slab_pool_t`.
A mutex is most commonly used by the slab pool while allocating and freeing
memory, but it can be used to protect any other user data structures allocated
in the shared zone.
To lock or unlock a mutex, call
`ngx_shmtx_lock(&shpool->mutex)` or
`ngx_shmtx_unlock(&shpool->mutex)` respectively.

```c
ngx_str_t        name;
ngx_foo_ctx_t   *ctx;
ngx_shm_zone_t  *shm_zone;

ngx_str_set(&name, "foo");

/* allocate shared zone context */
ctx = ngx_pcalloc(cf->pool, sizeof(ngx_foo_ctx_t));
if (ctx == NULL) {
    /* error */
}

/* add an entry for 64k shared zone */
shm_zone = ngx_shared_memory_add(cf, &name, 65536, &ngx_foo_module);
if (shm_zone == NULL) {
    /* error */
}

/* register init callback and context */
shm_zone->init = ngx_foo_init_zone;
shm_zone->data = ctx;


...


static ngx_int_t
ngx_foo_init_zone(ngx_shm_zone_t *shm_zone, void *data)
{
    ngx_foo_ctx_t  *octx = data;

    size_t            len;
    ngx_foo_ctx_t    *ctx;
    ngx_slab_pool_t  *shpool;

    value = shm_zone->data;

    if (octx) {
        /* reusing a shared zone from old cycle */
        ctx->value = octx->value;
        return NGX_OK;
    }

    shpool = (ngx_slab_pool_t *) shm_zone->shm.addr;

    if (shm_zone->shm.exists) {
        /* initialize shared zone context in Windows Angie worker */
        ctx->value = shpool->data;
        return NGX_OK;
    }

    /* initialize shared zone */

    ctx->value = ngx_slab_alloc(shpool, sizeof(ngx_uint_t));
    if (ctx->value == NULL) {
        return NGX_ERROR;
    }

    shpool->data = ctx->value;

    return NGX_OK;
}
```



### Logging

For logging, Angie uses `ngx_log_t` objects.
The Angie logger supports several types of output:

* stderr — logging to standard error (stderr)
* file — logging to a file
* syslog — logging to syslog
* memory — logging to internal memory storage for development purposes; the memory
  can be accessed later with a debugger

A logger instance can be a chain of loggers, linked to each other with
the `next` field.
In this case, each message is written to all loggers in the chain.

For each logger, a severity level controls which messages are written to the
log (only events assigned that level or higher are logged).
The following severity levels are supported:

* `NGX_LOG_EMERG`
* `NGX_LOG_ALERT`
* `NGX_LOG_CRIT`
* `NGX_LOG_ERR`
* `NGX_LOG_WARN`
* `NGX_LOG_NOTICE`
* `NGX_LOG_INFO`
* `NGX_LOG_DEBUG`

For debug logging, the debug mask is checked as well.
The debug masks are:

* `NGX_LOG_DEBUG_CORE`
* `NGX_LOG_DEBUG_ALLOC`
* `NGX_LOG_DEBUG_MUTEX`
* `NGX_LOG_DEBUG_EVENT`
* `NGX_LOG_DEBUG_HTTP`
* `NGX_LOG_DEBUG_MAIL`
* `NGX_LOG_DEBUG_STREAM`

Normally, loggers are created by existing Angie code from
`error_log` directives and are available at nearly every stage
of processing in cycle, configuration, client connection and other objects.

Angie provides the following logging macros:

* `ngx_log_error(level, log, err, fmt, ...)` — error logging
* `ngx_log_debug0(level, log, err, fmt)`,
  `ngx_log_debug1(level, log, err, fmt, arg1)` etc. — debug
  logging with up to eight supported formatting arguments

A log message is formatted in a buffer of size
`NGX_MAX_ERROR_STR` (currently, 2048 bytes) on the stack.
The message is prepended with the severity level, process ID (PID), connection
ID (stored in `log->connection`), and the system error text.
For non-debug messages, `log->handler` is called as well to
prepend more specific information to the log message.
The HTTP module sets the `ngx_http_log_error()` function as log
handler to log client and server addresses, current action (stored in
`log->action`), client request line, server name, etc.

```c
/* specify what is currently done */
log->action = "sending mp4 to client";

/* error and debug log */
ngx_log_error(NGX_LOG_INFO, c->log, 0, "client prematurely
              closed connection");

ngx_log_debug2(NGX_LOG_DEBUG_HTTP, mp4->file.log, 0,
               "mp4 start:%ui, length:%ui", mp4->start, mp4->length);
```

The example above results in log entries like these:

```text
2016/09/16 22:08:52 [info] 17445#0: *1 client prematurely closed connection while
sending mp4 to client, client: 127.0.0.1, server: , request: "GET /file.mp4 HTTP/1.1"
2016/09/16 23:28:33 [debug] 22140#0: *1 mp4 start:0, length:10000
```



### Cycles

A cycle object stores the Angie runtime context created from a specific
configuration.
Its type is `ngx_cycle_t`.
The current cycle is referenced by the `ngx_cycle` global
variable and inherited by Angie workers as they start.
Each time the Angie configuration is reloaded, a new cycle is created from the
new Angie configuration; the old cycle is usually deleted after the new one is
successfully created.

A cycle is created by the `ngx_init_cycle()` function, which
takes the previous cycle as its argument.
The function locates the previous cycle's configuration file and inherits as
many resources as possible from the previous cycle.
A placeholder cycle called "init cycle" is created at Angie start, then is
replaced by an actual cycle built from configuration.

Members of the cycle include:

* `pool` — Cycle pool.
  Created for each new cycle.
* `log` — Cycle log.
  Initially inherited from the old cycle, it is set to point to
  `new_log` after the configuration is read.
* `new_log` — Cycle log, created by the configuration.
  It's affected by the root-scope `error_log` directive.
* `connections`, `connection_n` —
  Array of connections of type `ngx_connection_t`, created by
  the event module while initializing each Angie worker.
  The `worker_connections` directive in the Angie configuration
  sets the number of connections `connection_n`.
* `free_connections`,
  `free_connection_n` — List and number of currently available
  connections.
  If no connections are available, an Angie worker refuses to accept new clients
  or connect to upstream servers.
* `files`, `files_n` — Array for mapping file
  descriptors to Angie connections.
  This mapping is used by the event modules having the
  `NGX_USE_FD_EVENT` flag (currently, it's
  `poll` and `devpoll`).
* `conf_ctx` — Array of core module configurations.
  The configurations are created and filled while reading Angie configuration
  files.
* `modules`, `modules_n` — Array of modules
  of type `ngx_module_t`, both static and dynamic, loaded by
  the current configuration.
* `listening` — Array of listening objects of type
  `ngx_listening_t`.
  Listening objects are normally added by the `listen`
  directive of different modules which call the
  `ngx_create_listening()` function.
  Listen sockets are created based on the listening objects.
* `paths` — Array of paths of type `ngx_path_t`.
  Paths are added by calling the function `ngx_add_path()` from
  modules which are going to operate on certain directories.
  These directories are created by Angie after reading configuration, if missing.
  Moreover, two handlers can be added for each path:
  * path loader — Executes only once in 60 seconds after starting or reloading
    Angie.
    Normally, the loader reads the directory and stores data in Angie shared
    memory.
    The handler is called from the dedicated Angie process "cache loader".
  * path manager — Executes periodically.
    Normally, the manager removes old files from the directory and updates Angie
    memory to reflect the changes.
    The handler is called from the dedicated "cache manager" process.
* `open_files` — List of open file objects of type
  `ngx_open_file_t`, which are created by calling the function
  `ngx_conf_open_file()`.
  Currently, Angie uses this kind of open files for logging.
  After reading the configuration, Angie opens all files in the
  `open_files` list and stores each file descriptor in the
  object's `fd` field.
  The files are opened in append mode and are created if missing.
  The files in the list are reopened by Angie workers upon receiving the
  reopen signal (most often `USR1`).
  In this case the descriptor in the `fd` field is changed to a
  new value.
* `shared_memory` — List of shared memory zones, each added by
  calling the `ngx_shared_memory_add()` function.
  Shared zones are mapped to the same address range in all Angie processes and
  are used to share common data, for example the HTTP cache in-memory tree.



### Buffer

For input/output operations, Angie provides the buffer type
`ngx_buf_t`.
Normally, it's used to hold data to be written to a destination or read from a
source.
A buffer can reference data in memory or in a file and it's technically
possible for a buffer to reference both at the same time.
Memory for the buffer is allocated separately and is not related to the buffer
structure `ngx_buf_t`.

The `ngx_buf_t` structure has the following fields:

* `start`, `end` — The boundaries of the memory
  block allocated for the buffer.
* `pos`, `last` — The boundaries of the memory
  buffer; normally a subrange of `start` ..
  `end`.
* `file_pos`, `file_last` — The boundaries of a
  file buffer, expressed as offsets from the beginning of the file.
* `tag` — Unique value used to distinguish buffers; created by
  different Angie modules, usually for the purpose of buffer reuse.
* `file` — File object.
* `temporary` — Flag indicating that the buffer references
  writable memory.
* `memory` — Flag indicating that the buffer references read-only
  memory.
* `in_file` — Flag indicating that the buffer references data
  in a file.
* `flush` — Flag indicating that all data prior to the buffer
  need to be flushed.
* `recycled` — Flag indicating that the buffer can be reused and
  needs to be consumed as soon as possible.
* `sync` — Flag indicating that the buffer carries no data or
  special signal like `flush` or `last_buf`.
  By default Angie considers such buffers an error condition, but this flag tells
  Angie to skip the error check.
* `last_buf` — Flag indicating that the buffer is the last in
  output.
* `last_in_chain` — Flag indicating that there are no more data
  buffers in a request or subrequest.
* `shadow` — Reference to another ("shadow") buffer related to
  the current buffer, usually in the sense that the buffer uses data from the
  shadow.
  When the buffer is consumed, the shadow buffer is normally also marked as
  consumed.
* `last_shadow` — Flag indicating that the buffer is the last
  one that references a particular shadow buffer.
* `temp_file` — Flag indicating that the buffer is in a temporary
  file.

For input and output operations buffers are linked in chains.
A chain is a sequence of chain links of type `ngx_chain_t`,
defined as follows:

```c
typedef struct ngx_chain_s  ngx_chain_t;

struct ngx_chain_s {
    ngx_buf_t    *buf;
    ngx_chain_t  *next;
};
```

Each chain link keeps a reference to its buffer and a reference to the next
chain link.

An example of using buffers and chains:

```c
ngx_chain_t *
ngx_get_my_chain(ngx_pool_t *pool)
{
    ngx_buf_t    *b;
    ngx_chain_t  *out, *cl, **ll;

    /* first buf */
    cl = ngx_alloc_chain_link(pool);
    if (cl == NULL) { /* error */ }

    b = ngx_calloc_buf(pool);
    if (b == NULL) { /* error */ }

    b->start = (u_char *) "foo";
    b->pos = b->start;
    b->end = b->start + 3;
    b->last = b->end;
    b->memory = 1; /* read-only memory */

    cl->buf = b;
    out = cl;
    ll = &cl->next;

    /* second buf */
    cl = ngx_alloc_chain_link(pool);
    if (cl == NULL) { /* error */ }

    b = ngx_create_temp_buf(pool, 3);
    if (b == NULL) { /* error */ }

    b->last = ngx_cpymem(b->last, "foo", 3);

    cl->buf = b;
    cl->next = NULL;
    *ll = cl;

    return out;
}
```



## Networking



### Connections

The connection type `ngx_connection_t` is a wrapper around a
socket descriptor.
It includes the following fields:

* `fd` — Socket descriptor
* `data` — Arbitrary connection context.
  Normally, it is a pointer to a higher-level object built on top of the
  connection, such as an HTTP request or a Stream session.
* `read`, `write` — Read and write events for
  the connection.
* `recv`, `send`,
  `recv_chain`, `send_chain` — I/O operations
  for the connection.
* `pool` — Connection pool.
* `log` — Connection log.
* `sockaddr`, `socklen`,
  `addr_text` — Remote socket address in binary and text forms.
* `local_sockaddr`, `local_socklen` — Local
  socket address in binary form.
  Initially, these fields are empty.
  Use the `ngx_connection_local_sockaddr()` function to get the
  local socket address.
* `proxy_protocol_addr`, `proxy_protocol_port`
  — PROXY protocol client address and port, if the PROXY protocol is enabled for
  the connection.
* `ssl` — SSL context for the connection.
* `reusable` — Flag indicating the connection is in a state that
  makes it eligible for reuse.
* `close` — Flag indicating that the connection is being reused
  and needs to be closed.

An Angie connection can transparently encapsulate the SSL layer.
In this case the connection's `ssl` field holds a pointer to an
`ngx_ssl_connection_t` structure, keeping all SSL-related data
for the connection, including `SSL_CTX` and
`SSL`.
The `recv`, `send`,
`recv_chain`, and `send_chain` handlers are
set to SSL-enabled functions as well.

The `worker_connections` directive in the Angie configuration
limits the number of connections per Angie worker.
All connection structures are precreated when a worker starts and stored in
the `connections` field of the cycle object.
To retrieve a connection structure, use the
`ngx_get_connection(s, log)` function.
It takes as its `s` argument a socket descriptor, which needs
to be wrapped in a connection structure.

Because the number of connections per worker is limited, Angie provides a
way to grab connections that are currently in use.
To enable or disable reuse of a connection, call the
`ngx_reusable_connection(c, reusable)` function.
Calling `ngx_reusable_connection(c, 1)` sets the
`reuse` flag in the connection structure and inserts the
connection into the `reusable_connections_queue` of the cycle.
Whenever `ngx_get_connection()` finds out there are no
available connections in the cycle's `free_connections` list,
it calls `ngx_drain_connections()` to release a
specific number of reusable connections.
For each such connection, the `close` flag is set and its read
handler is called which is supposed to free the connection by calling
`ngx_close_connection(c)` and make it available for reuse.
To exit the state when a connection can be reused,
`ngx_reusable_connection(c, 0)` is called.
HTTP client connections are an example of reusable connections in Angie; they
are marked as reusable until the first request byte is received from the client.



## Events



### Event

Event object `ngx_event_t` in Angie provides a mechanism
for notification that a specific event has occurred.

Fields in `ngx_event_t` include:

* `data` — Arbitrary event context used in event handlers,
  usually as a pointer to a connection related to the event.
* `handler` — Callback function to be invoked when the event
  happens.
* `write` — Flag indicating a write event.
  Absence of the flag indicates a read event.
* `active` — Flag indicating that the event is registered for
  receiving I/O notifications, normally from notification mechanisms like
  `epoll`, `kqueue`, `poll`.
* `ready` — Flag indicating that the event has received an
  I/O notification.
* `delayed` — Flag indicating that I/O is delayed due to rate
  limiting.
* `timer` — Red-black tree node for inserting the event into
  the timer tree.
* `timer_set` — Flag indicating that the event timer is set and
  not yet expired.
* `timedout` — Flag indicating that the event timer has expired.
* `eof` — Flag indicating that EOF occurred while reading data.
* `pending_eof` — Flag indicating that EOF is pending on the
  socket, even though there may be some data available before it.
  The flag is delivered via the `EPOLLRDHUP`
  `epoll` event or
  `EV_EOF` `kqueue` flag.
* `error` — Flag indicating that an error occurred during
  reading (for a read event) or writing (for a write event).
* `cancelable` — Timer event flag indicating that the event
  should be ignored while shutting down the worker.
  Graceful worker shutdown is delayed until there are no non-cancelable timer
  events scheduled.
* `posted` — Flag indicating that the event is posted to a queue.
* `queue` — Queue node for posting the event to a queue.



### I/O events

Each connection obtained by calling the `ngx_get_connection()`
function has two attached events, `c->read` and
`c->write`, which are used for receiving notification that the
socket is ready for reading or writing.
All such events operate in Edge-Triggered mode, meaning that they only trigger
notifications when the state of the socket changes.
For example, doing a partial read on a socket does not make Angie deliver a
repeated read notification until more data arrives on the socket.
Even when the underlying I/O notification mechanism is essentially
Level-Triggered (`poll`, `select` etc), Angie
converts the notifications to Edge-Triggered.
To make Angie event notifications consistent across all notifications systems
on different platforms, the functions
`ngx_handle_read_event(rev, flags)` and
`ngx_handle_write_event(wev, lowat)` must be called after
handling an I/O socket notification or calling any I/O functions on that socket.
Normally, the functions are called once at the end of each read or write
event handler.



### Timer events

An event can be set to send a notification when a timeout expires.
The timer used by events counts milliseconds since some unspecified point
in the past truncated to `ngx_msec_t` type.
Its current value can be obtained from the `ngx_current_msec`
variable.

The function `ngx_add_timer(ev, timer)` sets a timeout for an
event, `ngx_del_timer(ev)` deletes a previously set timeout.
The global timeout red-black tree `ngx_event_timer_rbtree`
stores all timeouts currently set.
The key in the tree is of type `ngx_msec_t` and is the time
when the event occurs.
The tree structure enables fast insertion and deletion operations, as well as
access to the nearest timeouts, which Angie uses to find out how long to wait
for I/O events and for expiring timeout events.



### Posted events

An event can be posted which means that its handler will be called at some
point later within the current event loop iteration.
Posting events is a good practice for simplifying code and escaping stack
overflows.
Posted events are held in a post queue.
The `ngx_post_event(ev, q)` macro posts the event
`ev` to the post queue `q`.
The `ngx_delete_posted_event(ev)` macro deletes the event
`ev` from the queue it's currently posted in.
Normally, events are posted to the `ngx_posted_events` queue,
which is processed late in the event loop — after all I/O and timer
events are already handled.
The function `ngx_event_process_posted()` is called to process
an event queue.
It calls event handlers until the queue is empty.
This means that a posted event handler can post more events to be processed
within the current event loop iteration.

An example:

```c
void
ngx_my_connection_read(ngx_connection_t *c)
{
    ngx_event_t  *rev;

    rev = c->read;

    ngx_add_timer(rev, 1000);

    rev->handler = ngx_my_read_handler;

    ngx_my_read(rev);
}


void
ngx_my_read_handler(ngx_event_t *rev)
{
    ssize_t            n;
    ngx_connection_t  *c;
    u_char             buf[256];

    if (rev->timedout) { /* timeout expired */ }

    c = rev->data;

    while (rev->ready) {
        n = c->recv(c, buf, sizeof(buf));

        if (n == NGX_AGAIN) {
            break;
        }

        if (n == NGX_ERROR) { /* error */ }

        /* process buf */
    }

    if (ngx_handle_read_event(rev, 0) != NGX_OK) { /* error */ }
}
```



### Event loop

Except for the Angie master process, all Angie processes do I/O and so have an
event loop.
(The Angie master process instead spends most of its time in the
`sigsuspend()` call waiting for signals to arrive.)
The Angie event loop is implemented in the
`ngx_process_events_and_timers()` function, which is called
repeatedly until the process exits.

The event loop has the following stages:

* Find the timeout that is closest to expiring, by calling
  `ngx_event_find_timer()`.
  This function finds the leftmost node in the timer tree and returns the
  number of milliseconds until the node expires.
* Process I/O events by calling a handler, specific to the event notification
  mechanism, chosen by Angie configuration.
  This handler waits for at least one I/O event to happen, but only until the next
  timeout expires.
  When a read or write event occurs, the `ready`
  flag is set and the event's handler is called.
  For Linux, the `ngx_epoll_process_events()` handler
  is normally used, which calls `epoll_wait()` to wait for I/O
  events.
* Expire timers by calling `ngx_event_expire_timers()`.
  The timer tree is iterated from the leftmost element to the right until an
  unexpired timeout is found.
  For each expired node the `timedout` event flag is set,
  the `timer_set` flag is reset, and the event handler is called.
* Process posted events by calling `ngx_event_process_posted()`.
  The function repeatedly removes the first element from the posted events
  queue and calls the element's handler, until the queue is empty.

All Angie processes handle signals as well.
Signal handlers only set global variables which are checked after the
`ngx_process_events_and_timers()` call.



### Processes

There are several types of processes in Angie.
The type of a process is kept in the `ngx_process`
global variable, and is one of the following:

* `NGX_PROCESS_MASTER` — The master process, which reads the
  NGINX configuration, creates cycles, and starts and controls child processes.
  It does not perform any I/O and responds only to signals.
  Its cycle function is `ngx_master_process_cycle()`.
* `NGX_PROCESS_WORKER` — The worker process, which handles client
  connections.
  It is started by the master process and responds to its signals and channel
  commands as well.
  Its cycle function is `ngx_worker_process_cycle()`.
  There can be multiple worker processes, as configured by the
  `worker_processes` directive.
* `NGX_PROCESS_SINGLE` — The single process, which exists only in
  `master_process off` mode, and is the only process running in
  that mode.
  It creates cycles (like the master process does) and handles client connections
  (like the worker process does).
  Its cycle function is `ngx_single_process_cycle()`.
* `NGX_PROCESS_HELPER` — The helper process, of which currently
  there are two types: cache manager and cache loader.
  The cycle function for both is
  `ngx_cache_manager_process_cycle()`.

The Angie processes handle the following signals:

* `NGX_SHUTDOWN_SIGNAL` (`SIGQUIT` on most
  systems) — Gracefully shutdown.
  Upon receiving this signal, the master process sends a shutdown signal to all
  child processes.
  When no child processes are left, the master destroys the cycle pool and exits.
  When a worker process receives this signal, it closes all listening sockets and
  waits until there are no non-cancelable events scheduled, then destroys the
  cycle pool and exits.
  When the cache manager or the cache loader process receives this signal, it
  exits immediately.
  The `ngx_quit` variable is set to `1` when a
  process receives this signal, and is immediately reset after being processed.
  The `ngx_exiting` variable is set to `1` while
  a worker process is in the shutdown state.
* `NGX_TERMINATE_SIGNAL` (`SIGTERM` on most
  systems) — Terminate.
  Upon receiving this signal, the master process sends a terminate signal to all
  child processes.
  If a child process does not exit within 1 second, the master process sends the
  `SIGKILL` signal to kill it.
  When no child processes are left, the master process destroys the cycle pool and
  exits.
  When a worker process, the cache manager process or the cache loader process
  receives this signal, it destroys the cycle pool and exits.
  The variable `ngx_terminate` is set to `1`
  when this signal is received.
* `NGX_NOACCEPT_SIGNAL` (`SIGWINCH` on most
  systems) — Shut down all worker and helper processes.
  Upon receiving this signal, the master process shuts down its child processes.
  If a previously started new Angie binary exits, the child processes of the old
  master are started again.
  When a worker process receives this signal, it shuts down in debug mode
  set by the `debug_points` directive.
* `NGX_RECONFIGURE_SIGNAL` (`SIGHUP` on most
  systems) — Reconfigure.
  Upon receiving this signal, the master process re-reads the configuration and
  creates a new cycle based on it.
  If the new cycle is created successfully, the old cycle is deleted and new
  child processes are started.
  Meanwhile, the old child processes receive the
  `NGX_SHUTDOWN_SIGNAL` signal.
  In single-process mode, Angie creates a new cycle, but keeps the old one until
  there are no longer clients with active connections tied to it.
  The worker and helper processes ignore this signal.
* `NGX_REOPEN_SIGNAL` (`SIGUSR1` on most
  systems) — Reopen files.
  The master process sends this signal to workers, which reopen all
  `open_files` related to the cycle.
* `NGX_CHANGEBIN_SIGNAL` (`SIGUSR2` on most
  systems) — Change the Angie binary.
  The master process starts a new Angie binary and passes in a list of all listen
  sockets.
  The text-format list, passed in the `"NGINX"` environment
  variable, consists of descriptor numbers separated with semicolons.
  The new Angie binary reads the `"NGINX"` variable and adds the
  sockets to its init cycle.
  Other processes ignore this signal.

While all Angie worker processes are able to receive and properly handle POSIX
signals, the master process does not use the standard `kill()`
syscall to pass signals to workers and helpers.
Instead, Angie uses inter-process socket pairs which allow sending messages
between all Angie processes.
Currently, however, messages are only sent from the master to its children.
The messages carry the standard signals.



### Threading

It is possible to offload into a separate thread tasks that would otherwise
block the Angie worker process.
For example, Angie can be configured to use threads to perform
[file I/O](https://en.angie.software//angie/docs/configuration/modules/http/index.md#aio).
Another use case is a library that doesn't have asynchronous interface
and thus cannot be normally used with Angie.
Keep in mind that the threads interface is a helper for the existing
asynchronous approach to processing client connections, and by no means
intended as a replacement.

To deal with synchronization, the following wrappers over
`pthreads` primitives are available:

* `typedef pthread_mutex_t  ngx_thread_mutex_t;`
  * `ngx_int_t
    ngx_thread_mutex_create(ngx_thread_mutex_t *mtx, ngx_log_t *log);`
  * `ngx_int_t
    ngx_thread_mutex_destroy(ngx_thread_mutex_t *mtx, ngx_log_t *log);`
  * `ngx_int_t
    ngx_thread_mutex_lock(ngx_thread_mutex_t *mtx, ngx_log_t *log);`
  * `ngx_int_t
    ngx_thread_mutex_unlock(ngx_thread_mutex_t *mtx, ngx_log_t *log);`
* `typedef pthread_cond_t  ngx_thread_cond_t;`
  * `ngx_int_t
    ngx_thread_cond_create(ngx_thread_cond_t *cond, ngx_log_t *log);`
  * `ngx_int_t
    ngx_thread_cond_destroy(ngx_thread_cond_t *cond, ngx_log_t *log);`
  * `ngx_int_t
    ngx_thread_cond_signal(ngx_thread_cond_t *cond, ngx_log_t *log);`
  * `ngx_int_t
    ngx_thread_cond_wait(ngx_thread_cond_t *cond, ngx_thread_mutex_t *mtx,
    ngx_log_t *log);`

Instead of creating a new thread for each task, Angie implements
a [thread_pool](https://en.angie.software//angie/docs/configuration/modules/core.md#thread-pool) strategy.
Multiple thread pools may be configured for different purposes
(for example, performing I/O on different sets of disks).
Each thread pool is created at startup and contains a limited number of threads
that process a queue of tasks.
When a task is completed, a predefined completion handler is called.

The `src/core/ngx_thread_pool.h` header file contains
relevant definitions:

```c
struct ngx_thread_task_s {
    ngx_thread_task_t   *next;
    ngx_uint_t           id;
    void                *ctx;
    void               (*handler)(void *data, ngx_log_t *log);
    ngx_event_t          event;
};

typedef struct ngx_thread_pool_s  ngx_thread_pool_t;

ngx_thread_pool_t *ngx_thread_pool_add(ngx_conf_t *cf, ngx_str_t *name);
ngx_thread_pool_t *ngx_thread_pool_get(ngx_cycle_t *cycle, ngx_str_t *name);

ngx_thread_task_t *ngx_thread_task_alloc(ngx_pool_t *pool, size_t size);
ngx_int_t ngx_thread_task_post(ngx_thread_pool_t *tp, ngx_thread_task_t *task);
```

At configuration time, a module willing to use threads has to obtain a
reference to a thread pool by calling
`ngx_thread_pool_add(cf, name)`, which either creates a
new thread pool with the given `name` or returns a reference
to the pool with that name if it already exists.

To add a `task` into a queue of a specified thread pool
`tp` at runtime, use the
`ngx_thread_task_post(tp, task)` function.

To execute a function in a thread, pass parameters and set up a completion
handler using the `ngx_thread_task_t` structure:

```c
typedef struct {
    int    foo;
} my_thread_ctx_t;


static void
my_thread_func(void *data, ngx_log_t *log)
{
    my_thread_ctx_t *ctx = data;

    /* this function is executed in a separate thread */
}


static void
my_thread_completion(ngx_event_t *ev)
{
    my_thread_ctx_t *ctx = ev->data;

    /* executed in Angie event loop */
}


ngx_int_t
my_task_offload(my_conf_t *conf)
{
    my_thread_ctx_t    *ctx;
    ngx_thread_task_t  *task;

    task = ngx_thread_task_alloc(conf->pool, sizeof(my_thread_ctx_t));
    if (task == NULL) {
        return NGX_ERROR;
    }

    ctx = task->ctx;

    ctx->foo = 42;

    task->handler = my_thread_func;
    task->event.handler = my_thread_completion;
    task->event.data = ctx;

    if (ngx_thread_task_post(conf->thread_pool, task) != NGX_OK) {
        return NGX_ERROR;
    }

    return NGX_OK;
}
```



## Modules



### Adding new modules

Each standalone Angie module resides in a separate directory that contains
at least two files:
`config` and a file with the module source code.
The `config` file contains all information needed for Angie to
integrate the module, for example:

```bash
ngx_module_type=CORE
ngx_module_name=ngx_foo_module
ngx_module_srcs="$ngx_addon_dir/ngx_foo_module.c"

. auto/module

ngx_addon_name=$ngx_module_name
```

The `config` file is a POSIX shell script that can set
and access the following variables:

* `ngx_module_type` — Type of module to build.
  Possible values are `CORE`, `HTTP`,
  `HTTP_FILTER`, `HTTP_INIT_FILTER`,
  `HTTP_AUX_FILTER`, `MAIL`,
  `STREAM`, or `MISC`.
* `ngx_module_name` — Module names.
  To build multiple modules from a set of source files, specify a
  whitespace-separated list of names.
  The first name indicates the name of the output binary for the dynamic module.
  The names in the list must match the names used in the source code.
* `ngx_addon_name` — Name of the module as it appears in output
  on the console from the configure script.
* `ngx_module_srcs` — Whitespace-separated list of source
  files used to compile the module.
  The `$ngx_addon_dir` variable can be used to represent the path
  to the module directory.
* `ngx_module_incs` — Include paths required to build the module
* `ngx_module_deps` — Whitespace-separated list of the module's
  dependencies.
  Usually, it is the list of header files.
* `ngx_module_libs` — Whitespace-separated list of libraries to
  link with the module.
  For example, use `ngx_module_libs=-lpthread` to link
  `libpthread` library.
  The following macros can be used to link against the same libraries as
  Angie:
  `LIBXSLT`, `LIBGD`, `GEOIP`,
  `PCRE`, `OPENSSL`, `MD5`,
  `SHA1`, `ZLIB`, and `PERL`.
* `ngx_module_link` — Variable set by the build system to
  `DYNAMIC` for a dynamic module or `ADDON`
  for a static module and used to determine different actions to perform
  depending on linking type.
* `ngx_module_order` — Load order for the module;
  useful for the `HTTP_FILTER` and
  `HTTP_AUX_FILTER` module types.
  The format for this option is a whitespace-separated list of modules.
  All modules in the list following the current module's name end up after it in
  the global list of modules, which sets up the order for modules initialization.
  For filter modules later initialization means earlier execution.

  The following modules are typically used as references.
  The `ngx_http_copy_filter_module` reads the data for other
  filter modules and is placed near the bottom of the list so that it is one of
  the first to be executed.
  The `ngx_http_write_filter_module` writes the data to the
  client socket and is placed near the top of the list, and is the last to be
  executed.

  By default, filter modules are placed before the
  `ngx_http_copy_filter` in the module list so that the filter
  handler is executed after the copy filter handler.
  For other module types the default is the empty string.

To compile a module into Angie statically, use the
`--add-module=`/path/to/module argument to the configure
script.
To compile a module for later dynamic loading into Angie, use the
`--add-dynamic-module=`/path/to/module argument.



### Core modules

Modules are the building blocks of Angie, and most of its functionality is
implemented as modules.
The module source file must contain a global variable of type
`ngx_module_t`, which is defined as follows:

```c
struct ngx_module_s {

    /* private part is omitted */

    void                 *ctx;
    ngx_command_t        *commands;
    ngx_uint_t            type;

    ngx_int_t           (*init_master)(ngx_log_t *log);

    ngx_int_t           (*init_module)(ngx_cycle_t *cycle);

    ngx_int_t           (*init_process)(ngx_cycle_t *cycle);
    ngx_int_t           (*init_thread)(ngx_cycle_t *cycle);
    void                (*exit_thread)(ngx_cycle_t *cycle);
    void                (*exit_process)(ngx_cycle_t *cycle);

    void                (*exit_master)(ngx_cycle_t *cycle);

    /* stubs for future extensions are omitted */
};
```

The omitted private part includes the module version and a signature and is
filled using the predefined macro `NGX_MODULE_V1`.

Each module keeps its private data in the `ctx` field,
recognizes the configuration directives, specified in the
`commands` array, and can be invoked at certain stages of
Angie lifecycle.
The module lifecycle consists of the following events:

* Configuration directive handlers are called as they appear
  in configuration files in the context of the master process.
* After the configuration is parsed successfully, `init_module`
  handler is called in the context of the master process.
  The `init_module` handler is called in the master process each
  time a configuration is loaded.
* The master process creates one or more worker processes and the
  `init_process` handler is called in each of them.
* When a worker process receives the shutdown or terminate command from the
  master, it invokes the `exit_process` handler.
* The master process calls the `exit_master` handler before
  exiting.

Because threads are used in Angie only as a supplementary I/O facility with its
own API, `init_thread` and `exit_thread`
handlers are not currently called.
There is also no `init_master` handler, because it would be
unnecessary overhead.

The module `type` defines exactly what is stored in the
`ctx` field.
Its value is one of the following types:

* `NGX_CORE_MODULE`
* `NGX_EVENT_MODULE`
* `NGX_HTTP_MODULE`
* `NGX_MAIL_MODULE`
* `NGX_STREAM_MODULE`

The `NGX_CORE_MODULE` is the most basic and thus the most
generic and most low-level type of module.
The other module types are implemented on top of it and provide a more
convenient way to deal with corresponding domains, like handling events or HTTP
requests.

The set of core modules includes `ngx_core_module`,
`ngx_errlog_module`, `ngx_regex_module`,
`ngx_thread_pool_module`, and
`ngx_openssl_module` modules.
The HTTP module, the stream module, the mail module, and event modules are core
modules too.
The context of a core module is defined as:

```c
typedef struct {
    ngx_str_t             name;
    void               *(*create_conf)(ngx_cycle_t *cycle);
    char               *(*init_conf)(ngx_cycle_t *cycle, void *conf);
} ngx_core_module_t;
```

where the `name` is a module name string,
`create_conf` and `init_conf`
are pointers to functions that create and initialize module configuration
respectively.
For core modules, Angie calls `create_conf` before parsing
a new configuration and `init_conf` after all configuration
is parsed successfully.
The typical `create_conf` function allocates memory for the
configuration and sets default values.

For example, a simplistic module called `ngx_foo_module` might
look like this:

```c
/*
 * Copyright (C) Author.
 */


#include 
#include 


typedef struct {
    ngx_flag_t  enable;
} ngx_foo_conf_t;


static void *ngx_foo_create_conf(ngx_cycle_t *cycle);
static char *ngx_foo_init_conf(ngx_cycle_t *cycle, void *conf);

static char *ngx_foo_enable(ngx_conf_t *cf, void *post, void *data);
static ngx_conf_post_t  ngx_foo_enable_post = { ngx_foo_enable };


static ngx_command_t  ngx_foo_commands[] = {

    { ngx_string("foo_enabled"),
      NGX_MAIN_CONF|NGX_DIRECT_CONF|NGX_CONF_FLAG,
      ngx_conf_set_flag_slot,
      0,
      offsetof(ngx_foo_conf_t, enable),
      &ngx_foo_enable_post },

      ngx_null_command
};


static ngx_core_module_t  ngx_foo_module_ctx = {
    ngx_string("foo"),
    ngx_foo_create_conf,
    ngx_foo_init_conf
};


ngx_module_t  ngx_foo_module = {
    NGX_MODULE_V1,
    &ngx_foo_module_ctx,                   /* module context */
    ngx_foo_commands,                      /* module directives */
    NGX_CORE_MODULE,                       /* module type */
    NULL,                                  /* init master */
    NULL,                                  /* init module */
    NULL,                                  /* init process */
    NULL,                                  /* init thread */
    NULL,                                  /* exit thread */
    NULL,                                  /* exit process */
    NULL,                                  /* exit master */
    NGX_MODULE_V1_PADDING
};


static void *
ngx_foo_create_conf(ngx_cycle_t *cycle)
{
    ngx_foo_conf_t  *fcf;

    fcf = ngx_pcalloc(cycle->pool, sizeof(ngx_foo_conf_t));
    if (fcf == NULL) {
        return NULL;
    }

    fcf->enable = NGX_CONF_UNSET;

    return fcf;
}


static char *
ngx_foo_init_conf(ngx_cycle_t *cycle, void *conf)
{
    ngx_foo_conf_t *fcf = conf;

    ngx_conf_init_value(fcf->enable, 0);

    return NGX_CONF_OK;
}


static char *
ngx_foo_enable(ngx_conf_t *cf, void *post, void *data)
{
    ngx_flag_t  *fp = data;

    if (*fp == 0) {
        return NGX_CONF_OK;
    }

    ngx_log_error(NGX_LOG_NOTICE, cf->log, 0, "Foo Module is enabled");

    return NGX_CONF_OK;
}
```



### Configuration Directives

The `ngx_command_t` type defines a single configuration directive.
Each module that supports configuration provides an array of such structures
that describe how to process arguments and what handlers to call:

```c
typedef struct ngx_command_s  ngx_command_t;

struct ngx_command_s {
    ngx_str_t             name;
    ngx_uint_t            type;
    char               *(*set)(ngx_conf_t *cf, ngx_command_t *cmd, void *conf);
    ngx_uint_t            conf;
    ngx_uint_t            offset;
    void                 *post;
};
```

Terminate the array with the special value `ngx_null_command`.
The `name` is the name of the directive as it appears
in the configuration file, for example, "worker_processes" or "listen".
The `type` is a bitfield of flags that specify the number of
arguments the directive takes, its type, and the context in which it appears.
The flags are:

* `NGX_CONF_NOARGS` — The directive takes no arguments.
* `NGX_CONF_1MORE` — The directive takes one or more arguments.
* `NGX_CONF_2MORE` — The directive takes two or more arguments.
* `NGX_CONF_TAKE1` .. `NGX_CONF_TAKE7` —
  The directive takes exactly the indicated number of arguments.
* `NGX_CONF_TAKE12`, `NGX_CONF_TAKE13`,
  `NGX_CONF_TAKE23`, `NGX_CONF_TAKE123`,
  `NGX_CONF_TAKE1234` — The directive can take a different number of
  arguments.
  Options are limited to the specified numbers.
  For example, `NGX_CONF_TAKE12` means it takes one or two
  arguments.

Flags for directive types:

* `NGX_CONF_BLOCK` — The directive is a block, that is, it can
  contain other directives within its opening and closing braces, or even
  implement its own parser to handle content inside.
* `NGX_CONF_FLAG` — The directive takes a boolean value, either
  `on` or `off`.

The directive context defines where it can appear in the configuration:

* `NGX_MAIN_CONF` — In the top-level context.
* `NGX_HTTP_MAIN_CONF` — In the `http` block.
* `NGX_HTTP_SRV_CONF` — In a `server` block
  within the `http` block.
* `NGX_HTTP_LOC_CONF` — In a `location` block
  within the `http` block.
* `NGX_HTTP_UPS_CONF` — In an `upstream` block
  within the `http` block.
* `NGX_HTTP_SIF_CONF` — In an `if` block within
  a `server` block in the `http` block.
* `NGX_HTTP_LIF_CONF` — In an `if` block within
  a `location` block in the `http` block.
* `NGX_HTTP_LMT_CONF` — In a `limit_except` block
  within the `http` block.
* `NGX_STREAM_MAIN_CONF` — In the `stream` block.
* `NGX_STREAM_SRV_CONF` — In a `server` block
  within the `stream` block.
* `NGX_STREAM_UPS_CONF` — In an `upstream` block
  within the `stream` block.
* `NGX_MAIL_MAIN_CONF` — In the `mail` block.
* `NGX_MAIL_SRV_CONF` — In a `server` block
  within the `mail` block.
* `NGX_EVENT_CONF` — In the `events` block.
* `NGX_DIRECT_CONF` — Used by modules that don't
  create a hierarchy of contexts and have only a single global configuration.
  This configuration is passed to the handler as the `conf` argument.

The configuration parser uses these flags to throw an error for a
misplaced directive and calls directive handlers supplied with the appropriate
configuration pointer, so that the same directives in different locations can
store their values in distinct locations.

The `set` field defines a handler that processes the directive
and stores parsed values into the corresponding configuration.
There are a number of functions that perform common conversions:

* `ngx_conf_set_flag_slot` — Converts the literal strings
  `on` and `off` into an
  `ngx_flag_t` value with values 1 or 0, respectively.
* `ngx_conf_set_str_slot` — Stores a string as a value of the
  `ngx_str_t` type.
* `ngx_conf_set_str_array_slot` — Appends a value to an array
  `ngx_array_t` of strings `ngx_str_t`.
  The array is created if it does not already exist.
* `ngx_conf_set_keyval_slot` — Appends a key-value pair to an
  array `ngx_array_t` of key-value pairs
  `ngx_keyval_t`.
  The first string becomes the key and the second the value.
  The array is created if it does not already exist.
* `ngx_conf_set_num_slot` — Converts a directive's argument
  to an `ngx_int_t` value.
* `ngx_conf_set_size_slot` — Converts a
  [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units) to a `size_t` value
  expressed in bytes.
* `ngx_conf_set_off_slot` — Converts an
  [offset](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units) to an `off_t` value
  expressed in bytes.
* `ngx_conf_set_msec_slot` — Converts a
  [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units) to an `ngx_msec_t` value
  expressed in milliseconds.
* `ngx_conf_set_sec_slot` — Converts a
  [time](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units) to a `time_t` value
  expressed in seconds.
* `ngx_conf_set_bufs_slot` — Converts the two supplied arguments
  into an `ngx_bufs_t` object that holds the number and
  [size](https://en.angie.software//angie/docs/configuration/configfile.md#measurement-units) of buffers.
* `ngx_conf_set_enum_slot` — Converts the supplied argument
  to an `ngx_uint_t` value.
  The null-terminated array of `ngx_conf_enum_t` passed in the
  `post` field defines the acceptable strings and corresponding
  integer values.
* `ngx_conf_set_bitmask_slot` — Converts the supplied arguments
  to an `ngx_uint_t` value.
  The mask values for each argument are ORed producing the result.
  The null-terminated array of `ngx_conf_bitmask_t` passed in the
  `post` field defines the acceptable strings and corresponding
  mask values.
* `ngx_conf_set_path_slot` — Converts the supplied arguments to an
  `ngx_path_t` value and performs all necessary initializations.
  For details, see the documentation for the
  [proxy_temp_path](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-temp-path) directive.
* `ngx_conf_set_access_slot` — Converts the supplied arguments to a file
  permissions mask.
  For details, see the documentation for the
  [proxy_store_access](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-store-access) directive.

The `conf` field defines which configuration structure
is passed to the directive handler.
Core modules only have the global configuration and set the
`NGX_DIRECT_CONF` flag to access it.
Modules such as HTTP, Stream, or Mail create hierarchies of configurations.
For example, a module's configuration is created for the `server`,
`location`, and `if` scopes.

* `NGX_HTTP_MAIN_CONF_OFFSET` — Configuration for the
  `http` block.
* `NGX_HTTP_SRV_CONF_OFFSET` — Configuration for a
  `server` block within the `http` block.
* `NGX_HTTP_LOC_CONF_OFFSET` — Configuration for a
  `location` block within the `http` block.
* `NGX_STREAM_MAIN_CONF_OFFSET` — Configuration for the
  `stream` block.
* `NGX_STREAM_SRV_CONF_OFFSET` — Configuration for a
  `server` block within the `stream` block.
* `NGX_MAIL_MAIN_CONF_OFFSET` — Configuration for the
  `mail` block.
* `NGX_MAIL_SRV_CONF_OFFSET` — Configuration for a
  `server` block within the `mail` block.

The `offset` field defines the offset of a field in a module's configuration
structure that holds values for this particular directive.
The typical use is to employ the `offsetof()` macro.

The `post` field has two purposes: it can be used to define
a handler to be called after the main handler has completed, or to pass
additional data to the main handler.
In the first case, the `ngx_conf_post_t` structure needs to
be initialized with a pointer to the handler, for example:

```c
static char *ngx_do_foo(ngx_conf_t *cf, void *post, void *data);
static ngx_conf_post_t  ngx_foo_post = { ngx_do_foo };
```

The `post` argument is the `ngx_conf_post_t`
object itself, and the `data` is a pointer to the value,
converted from arguments by the main handler with the appropriate type.



## HTTP



### Connection

Each HTTP client connection runs through the following stages:

* `ngx_event_accept()` accepts a client TCP connection.
  This handler is called in response to a read notification on a listen socket.
  A new `ngx_connection_t` object is created at this stage
  to wrap the newly accepted client socket.
  Each Angie listener provides a handler to pass the new connection object to.
  For HTTP connections it's `ngx_http_init_connection(c)`.
* `ngx_http_init_connection()` performs early initialization of
  the HTTP connection.
  At this stage an `ngx_http_connection_t` object is created for
  the connection and its reference is stored in the connection's
  `data` field.
  Later it will be replaced by an HTTP request object.
  A PROXY protocol parser and the SSL handshake are started at
  this stage as well.
* `ngx_http_wait_request_handler()` read event handler
  is called when data is available on the client socket.
  At this stage an HTTP request object `ngx_http_request_t` is
  created and set to the connection's `data` field.
* `ngx_http_process_request_line()` read event handler
  reads client request line.
  The handler is set by `ngx_http_wait_request_handler()`.
  The data is read into connection's `buffer`.
  The size of the buffer is initially set by the directive
  [client_header_buffer_size](https://en.angie.software//angie/docs/configuration/modules/http/index.md#client-header-buffer-size).
  The entire client header is supposed to fit in the buffer.
  If the initial size is not sufficient, a bigger buffer is allocated,
  with the capacity set by the [large_client_header_buffers](https://en.angie.software//angie/docs/configuration/modules/http/index.md#large-client-header-buffers)
  directive.
* `ngx_http_process_request_headers()` read event handler,
  is set after `ngx_http_process_request_line()` to read
  the client request header.
* `ngx_http_core_run_phases()` is called when the request header
  is completely read and parsed.
  This function runs request phases from
  `NGX_HTTP_POST_READ_PHASE` to
  `NGX_HTTP_CONTENT_PHASE`.
  The last phase is intended to generate a response and pass it along the filter
  chain.
  The response is not necessarily sent to the client at this phase.
  It might remain buffered and be sent at the finalization stage.
* `ngx_http_finalize_request()` is usually called when the
  request has generated all the output or produced an error.
  In the latter case an appropriate error page is looked up and used as the
  response.
  If the response is not completely sent to the client by this point, an
  HTTP writer `ngx_http_writer()` is activated to finish
  sending outstanding data.
* `ngx_http_finalize_connection()` is called when the complete
  response has been sent to the client and the request can be destroyed.
  If the client connection keepalive feature is enabled,
  `ngx_http_set_keepalive()` is called, which destroys the
  current request and waits for the next request on the connection.
  Otherwise, `ngx_http_close_request()` destroys both the
  request and the connection.



### Request

For each client HTTP request the `ngx_http_request_t` object is
created.  Some of the fields of this object are:

* `connection` — Pointer to a `ngx_connection_t`
  client connection object.
  Several requests can reference the same connection object at the same time -
  one main request and its subrequests.
  After a request is deleted, a new request can be created on the same connection.

  Note that for HTTP connections `ngx_connection_t`'s
  `data` field points back to the request.
  Such requests are called active, as opposed to the other requests tied to the
  connection.
  An active request is used to handle client connection events and is allowed to
  output its response to the client.
  Normally, each request becomes active at some point so that it can send its
  output.
* `ctx` — Array of HTTP module contexts.
  Each module of type `NGX_HTTP_MODULE` can store any value
  (normally, a pointer to a structure) in the request.
  The value is stored in the `ctx` array at the module's
  `ctx_index` position.
  The following macros provide a convenient way to get and set request contexts:
  * `ngx_http_get_module_ctx(r, module)` — Returns
    the `module`'s context
  * `ngx_http_set_ctx(r, c, module)` — Sets `c`
    as the `module`'s context
* `main_conf`, `srv_conf`,
  `loc_conf` — Arrays of current request
  configurations.
  Configurations are stored at the module's `ctx_index`
  positions.
* `read_event_handler`, `write_event_handler` -
  Read and write event handlers for the request.
  Normally, both the read and write event handlers for an HTTP connection
  are set to `ngx_http_request_handler()`.
  This function calls the `read_event_handler` and
  `write_event_handler` handlers for the currently
  active request.
* `cache` — Request cache object for caching the
  upstream response.
* `upstream` — Request upstream object for proxying.
* `pool` — Request pool.
  The request object itself is allocated in this pool, which is destroyed when
  the request is deleted.
  For allocations that need to be available throughout the client connection's
  lifetime, use `ngx_connection_t`'s pool instead.
* `header_in` — Buffer into which the client HTTP request
  header is read.
* `headers_in`, `headers_out` — Input and
  output HTTP headers objects.
  Both objects contain the `headers` field of type
  `ngx_list_t` for keeping the raw list of headers.
  In addition to that, specific headers are available for getting and setting as
  separate fields, for example `content_length_n`,
  `status` etc.
* `request_body` — Client request body object.
* `start_sec`, `start_msec` — Time point when
  the request was created, used for tracking request duration.
* `method`, `method_name` — Numeric and text
  representation of the client HTTP request method.
  Numeric values for methods are defined in
  `src/http/ngx_http_request.h` with the macros
  `NGX_HTTP_GET`, `NGX_HTTP_HEAD`,
  `NGX_HTTP_POST`, etc.
* `http_protocol`  — Client HTTP protocol version in its
  original text form ("HTTP/1.0", "HTTP/1.1" etc).
* `http_version`  — Client HTTP protocol version in
  numeric form  (`NGX_HTTP_VERSION_10`,
  `NGX_HTTP_VERSION_11`, etc.).
* `http_major`, `http_minor`  — Client HTTP
  protocol version in numeric form split into major and minor parts.
* `request_line`, `unparsed_uri` — Request line
  and URI in the original client request.
* `uri`, `args`, `exten` —
  URI, arguments and file extension for the current request.
  The URI value here might differ from the original URI sent by the client due to
  normalization.
  Throughout request processing, these values can change as internal redirects
  are performed.
* `main` — Pointer to a main request object.
  This object is created to process a client HTTP request, as opposed to
  subrequests, which are created to perform a specific subtask within the main
  request.
* `parent` — Pointer to the parent request of a subrequest.
* `postponed` — List of output buffers and subrequests, in the
  order in which they are sent and created.
  The list is used by the postpone filter to provide consistent request output
  when parts of it are created by subrequests.
* `post_subrequest` — Pointer to a handler with the context
  to be called when a subrequest gets finalized.
  Unused for main requests.
* `posted_requests` — List of requests to be started or
  resumed, which is done by calling the request's
  `write_event_handler`.
  Normally, this handler holds the request main function, which at first runs
  request phases and then produces the output.

  A request is usually posted by the
  `ngx_http_post_request(r, NULL)` call.
  It is always posted to the main request `posted_requests` list.
  The function `ngx_http_run_posted_requests(c)` runs all
  requests that are posted in the main request of the passed
  connection's active request.
  All event handlers call `ngx_http_run_posted_requests`,
  which can lead to new posted requests.
  Normally, it is called after invoking a request's read or write handler.
* `phase_handler` — Index of current request phase.
* `ncaptures`, `captures`,
  `captures_data` — Regex captures produced
  by the last regex match of the request.
  A regex match can occur at a number of places during request processing:
  map lookup, server lookup by SNI or HTTP Host, rewrite, proxy_redirect, etc.
  Captures produced by a lookup are stored in the above mentioned fields.
  The field `ncaptures` holds the number of captures,
  `captures` holds captures boundaries and
  `captures_data` holds the string against which the regex was
  matched and which is used to extract captures.
  After each new regex match, request captures are reset to hold new values.
* `count` — Request reference counter.
  The field only makes sense for the main request.
  Increasing the counter is done by simple `r->main->count++`.
  To decrease the counter, call
  `ngx_http_finalize_request(r, rc)`.
  Creation of a subrequest and running the request body read process both
  increment the counter.
* `subrequests` — Current subrequest nesting level.
  Each subrequest inherits its parent's nesting level, decreased by one.
  An error is generated if the value reaches zero.
  The value for the main request is defined by the
  `NGX_HTTP_MAX_SUBREQUESTS` constant.
* `uri_changes` — Number of URI changes remaining for
  the request.
  The total number of times a request can change its URI is limited by the
  `NGX_HTTP_MAX_URI_CHANGES` constant.
  With each change the value is decremented until it reaches zero, at which point
  an error is generated.
  Rewrites and internal redirects to normal or named locations are considered URI changes.
* `blocked` — Counter of blocks held on the request.
  While this value is non-zero, the request cannot be finalized.
  Currently, this value is increased by pending AIO operations (POSIX AIO and
  thread operations) and active cache locks.
* `buffered` — Bitmask showing which modules have buffered
  output produced by the request.
  A number of filters can buffer output; for example, sub_filter can buffer data
  because of a partial string match, copy filter can buffer data because of
  a lack of free output buffers, etc.
  As long as this value is non-zero, the request is not finalized,
  pending a flush.
* `header_only` — Flag indicating that output does not require
  a body.
  For example, this flag is used by HTTP HEAD requests.
* `keepalive` — Flag indicating whether client connection
  keepalive is supported.
  The value is inferred from the HTTP version and the value of the
  "Connection" header.
* `header_sent` — Flag indicating that the output header
  has already been sent by the request.
* `internal` — Flag indicating that the current request
  is internal.
  To enter the internal state, a request must pass through an internal
  redirect or be a subrequest.
  Internal requests are allowed to enter internal locations.
* `allow_ranges` — Flag indicating that a partial response
  can be sent to the client, as requested by the HTTP Range header.
* `subrequest_ranges` — Flag indicating that a partial response
  can be sent while processing a subrequest.
* `single_range` — Flag indicating that only a single continuous
  range of output data can be sent to the client.
  This flag is usually set when sending a stream of data, for example, from
  a proxy server, and the entire response is not available in a single buffer.
* `main_filter_need_in_memory`,
  `filter_need_in_memory` — Flags
  requesting that output be produced in memory buffers but not in files.
  This is a signal to the copy filter to read data from file buffers even if
  sendfile is enabled.
  The difference between the two flags is the location of the filter modules that
  set them.
  Filters called before the postpone filter in the filter chain set
  `filter_need_in_memory`, requesting that only the current
  request's output come into memory buffers.
  Filters called later in the filter chain set
  `main_filter_need_in_memory`, requesting that both
  the main request and all subrequests read files into memory
  when sending output.
* `filter_need_temporary` — Flag requesting that the request output
  be produced in temporary buffers, but not in read-only memory buffers or
  file buffers.
  This is used by filters that may change the output directly in the buffers where
  it is sent.



### HTTP Module Configuration

Each HTTP module can have three types of configuration:

* Main configuration — Applies to the entire `http` block.
  Serves as global settings for the module.
* Server configuration — Applies to a single `server` block.
  Serves as server-specific settings for the module.
* Location configuration — Applies to a single `location`,
  `if`, or `limit_except` block.
  Serves as location-specific settings for the module.

Configuration structures are created at the Angie configuration stage by
calling functions that allocate the structures, initialize them,
and merge them.
The following example shows how to create a simple location configuration
for a module.
The configuration has one setting, `foo`, of type
unsigned integer.

```c
typedef struct {
    ngx_uint_t  foo;
} ngx_http_foo_loc_conf_t;


static ngx_http_module_t  ngx_http_foo_module_ctx = {
    NULL,                                  /* preconfiguration */
    NULL,                                  /* postconfiguration */

    NULL,                                  /* create main configuration */
    NULL,                                  /* init main configuration */

    NULL,                                  /* create server configuration */
    NULL,                                  /* merge server configuration */

    ngx_http_foo_create_loc_conf,          /* create location configuration */
    ngx_http_foo_merge_loc_conf            /* merge location configuration */
};


static void *
ngx_http_foo_create_loc_conf(ngx_conf_t *cf)
{
    ngx_http_foo_loc_conf_t  *conf;

    conf = ngx_pcalloc(cf->pool, sizeof(ngx_http_foo_loc_conf_t));
    if (conf == NULL) {
        return NULL;
    }

    conf->foo = NGX_CONF_UNSET_UINT;

    return conf;
}


static char *
ngx_http_foo_merge_loc_conf(ngx_conf_t *cf, void *parent, void *child)
{
    ngx_http_foo_loc_conf_t *prev = parent;
    ngx_http_foo_loc_conf_t *conf = child;

    ngx_conf_merge_uint_value(conf->foo, prev->foo, 1);
}
```

As seen in the example, the `ngx_http_foo_create_loc_conf()`
function creates a new configuration structure, and
`ngx_http_foo_merge_loc_conf()` merges a configuration with
configuration from a higher level.
In fact, server and location configurations exist not only at the server
and location levels, but are also created for all levels above them.
Specifically, a server configuration is also created at the main level, and
location configurations are created at the main, server, and location levels.
These configurations make it possible to specify server- and location-specific
settings at any level of an Angie configuration file.
Eventually configurations are merged down.
A number of macros, such as `NGX_CONF_UNSET` and
`NGX_CONF_UNSET_UINT`, are provided for indicating a missing setting
and ignoring it during the merge.
Standard Angie merge macros, such as `ngx_conf_merge_value()` and
`ngx_conf_merge_uint_value()`, provide a convenient way to
merge a setting and set the default value if none of the configurations
provided an explicit value.
For a complete list of macros for different types, see
`src/core/ngx_conf_file.h`.

The following macros are available
for accessing configuration of HTTP modules at configuration time.
They all take `ngx_conf_t` reference as the first argument.

* `ngx_http_conf_get_module_main_conf(cf, module)`
* `ngx_http_conf_get_module_srv_conf(cf, module)`
* `ngx_http_conf_get_module_loc_conf(cf, module)`

The following example obtains a pointer to a location configuration
of the standard [HTTP](https://en.angie.software//angie/docs/configuration/modules/http/index.md#http-core) module
and replaces the location content handler stored
in the `handler` field of the structure.

```c
static ngx_int_t ngx_http_foo_handler(ngx_http_request_t *r);


static ngx_command_t  ngx_http_foo_commands[] = {

    { ngx_string("foo"),
      NGX_HTTP_LOC_CONF|NGX_CONF_NOARGS,
      ngx_http_foo,
      0,
      0,
      NULL },

      ngx_null_command
};


static char *
ngx_http_foo(ngx_conf_t *cf, ngx_command_t *cmd, void *conf)
{
    ngx_http_core_loc_conf_t  *clcf;

    clcf = ngx_http_conf_get_module_loc_conf(cf, ngx_http_core_module);
    clcf->handler = ngx_http_bar_handler;

    return NGX_CONF_OK;
}
```

The following macros are available for accessing configuration of HTTP modules
at runtime.

* `ngx_http_get_module_main_conf(r, module)`
* `ngx_http_get_module_srv_conf(r, module)`
* `ngx_http_get_module_loc_conf(r, module)`

These macros receive a reference to an HTTP request
`ngx_http_request_t`.
The main configuration of a request never changes.
Server configuration can change from the default after
choosing a virtual server for a request.
The location configuration selected for processing a request can change
multiple times as a result of a rewrite operation or internal redirect.
The following example shows how to access HTTP configuration of a module
at runtime.

```c
static ngx_int_t
ngx_http_foo_handler(ngx_http_request_t *r)
{
    ngx_http_foo_loc_conf_t  *flcf;

    flcf = ngx_http_get_module_loc_conf(r, ngx_http_foo_module);

    ...
}
```



### Phases

Each HTTP request passes through a sequence of phases.
In each phase a distinct type of processing is performed on the request.
Module-specific handlers can be registered in most phases,
and many standard Angie modules register their phase handlers as a way of
being invoked at a specific stage of request processing.
Phases are processed successively and the phase handlers are called
once the request reaches the phase.
Following is the list of Angie HTTP phases.

* `NGX_HTTP_POST_READ_PHASE` — First phase.
  The [RealIP](https://en.angie.software//angie/docs/configuration/modules/http/http_realip.md#http-realip) module
  registers its handler at this phase to enable
  substitution of client addresses before any other module is invoked.
* `NGX_HTTP_SERVER_REWRITE_PHASE` — Phase where
  rewrite directives defined in a `server` block
  (but outside a `location` block) are processed.
  The [Rewrite](https://en.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#http-rewrite) module
  installs its handler at this phase.
* `NGX_HTTP_FIND_CONFIG_PHASE` — Special phase where
  a location is chosen based on the request URI.
  Before this phase, the default location for the relevant virtual server is assigned to the
  request, and any module requesting a location configuration
  receives the configuration for the default server location.
  This phase assigns a new location to the request.
  No additional handlers can be registered at this phase.
* `NGX_HTTP_REWRITE_PHASE` — Same as
  `NGX_HTTP_SERVER_REWRITE_PHASE`, but for
  rewrite rules defined in the location chosen in the previous phase.
* `NGX_HTTP_POST_REWRITE_PHASE` — Special phase where
  the request is redirected to a new location if its URI changed
  during a rewrite.
  This is implemented by the request going through the
  `NGX_HTTP_FIND_CONFIG_PHASE` again.
  No additional handlers can be registered at this phase.
* `NGX_HTTP_PREACCESS_PHASE` — A common phase for different
  types of handlers, not associated with access control.
  The standard Angie modules
  [Limit Conn](https://en.angie.software//angie/docs/configuration/modules/http/http_limit_conn.md#http-limit-conn) and
  [Limit Req](https://en.angie.software//angie/docs/configuration/modules/http/http_limit_req.md#http-limit-req) register their handlers at this phase.
* `NGX_HTTP_ACCESS_PHASE` — Phase where it is verified
  that the client is authorized to make the request.
  Standard Angie modules such as
  [Access](https://en.angie.software//angie/docs/configuration/modules/http/http_access.md#http-access) and
  [Auth Basic](https://en.angie.software//angie/docs/configuration/modules/http/http_auth_basic.md#http-auth-basic) register their handlers at this phase.
  By default the client must pass the authorization check of all handlers
  registered at this phase for the request to continue to the next phase.
  The [satisfy](https://en.angie.software//angie/docs/configuration/modules/http/index.md#satisfy) directive
  can be used to permit processing to continue if any of the phase handlers
  authorizes the client.
* `NGX_HTTP_POST_ACCESS_PHASE` — Special phase where the
  [satisfy](https://en.angie.software//angie/docs/configuration/modules/http/index.md#satisfy) directive is processed.
  If some access phase handlers denied access and none explicitly allowed it,
  the request is finalized.
  No additional handlers can be registered at this phase.
* `NGX_HTTP_PRECONTENT_PHASE` — Phase for handlers to be called
  prior to generating content.
  Standard modules such as
  [try_files](https://en.angie.software//angie/docs/configuration/modules/http/index.md#try-files) and
  [Mirror](https://en.angie.software//angie/docs/configuration/modules/http/http_mirror.md#http-mirror)
  register their handlers at this phase.
* `NGX_HTTP_CONTENT_PHASE` — Phase where the response
  is normally generated.
  Multiple standard Angie modules register their handlers at this phase,
  including
  [Index](https://en.angie.software//angie/docs/configuration/modules/http/http_index.md#http-index).
  They are called sequentially until one of them produces
  the output.
  It's also possible to set content handlers on a per-location basis.
  If the [HTTP](https://en.angie.software//angie/docs/configuration/modules/http/index.md#http-core) module's location configuration has
  `handler` set, it is called as the content handler
  and the handlers installed at this phase are ignored.
* `NGX_HTTP_LOG_PHASE` — Phase where request
  logging is performed.
  Currently, only the
  [Log](https://en.angie.software//angie/docs/configuration/modules/http/http_log.md#http-log) module
  registers its handler
  at this stage for access logging.
  Log phase handlers are called at the very end of request processing, right
  before freeing the request.

Following is an example of a preaccess phase handler.

```c
static ngx_http_module_t  ngx_http_foo_module_ctx = {
    NULL,                                  /* preconfiguration */
    ngx_http_foo_init,                     /* postconfiguration */

    NULL,                                  /* create main configuration */
    NULL,                                  /* init main configuration */

    NULL,                                  /* create server configuration */
    NULL,                                  /* merge server configuration */

    NULL,                                  /* create location configuration */
    NULL                                   /* merge location configuration */
};


static ngx_int_t
ngx_http_foo_handler(ngx_http_request_t *r)
{
    ngx_table_elt_t  *ua;

    ua = r->headers_in.user_agent;

    if (ua == NULL) {
        return NGX_DECLINED;
    }

    /* reject requests with "User-Agent: foo" */
    if (ua->value.len == 3 && ngx_strncmp(ua->value.data, "foo", 3) == 0) {
        return NGX_HTTP_FORBIDDEN;
    }

    return NGX_DECLINED;
}


static ngx_int_t
ngx_http_foo_init(ngx_conf_t *cf)
{
    ngx_http_handler_pt        *h;
    ngx_http_core_main_conf_t  *cmcf;

    cmcf = ngx_http_conf_get_module_main_conf(cf, ngx_http_core_module);

    h = ngx_array_push(&cmcf->phases[NGX_HTTP_PREACCESS_PHASE].handlers);
    if (h == NULL) {
        return NGX_ERROR;
    }

    *h = ngx_http_foo_handler;

    return NGX_OK;
}
```

Phase handlers are expected to return specific codes:

* `NGX_OK` — proceed to the next phase.
* `NGX_DECLINED` — proceed to the next handler of the current
  phase.
  If the current handler is the last in the current phase,
  move to the next phase.
* `NGX_AGAIN`, `NGX_DONE` — suspend
  phase handling until some future event, which could be
  an asynchronous I/O operation or just a delay, for example.
  It is assumed that phase handling will be resumed later by calling
  `ngx_http_core_run_phases()`.
* Any other value returned by the phase handler is treated as a request
  finalization code, in particular, an HTTP response code.
  The request is finalized with the provided code.

For some phases, return codes are treated in a slightly different way.
At the content phase, any return code other than
`NGX_DECLINED` is considered a finalization code.
Any return code from the location content handlers is considered
a finalization code.
At the access phase, in
[satisfy any](https://en.angie.software//angie/docs/configuration/modules/http/index.md#satisfy) mode,
returning a code other than `NGX_OK`,
`NGX_DECLINED`, `NGX_AGAIN`,
`NGX_DONE` is considered a denial.
If no subsequent access handlers allow or deny access with a different
code, the denial code will become the finalization code.



### Examples

The
[nginx-dev-examples](https://github.com/nginx/nginx-dev-examples)
repository provides examples of nginx modules suitable for Angie as well.



## Code style



### General rules

* maximum text width is 80 characters
* indentation is 4 spaces
* no tabs, no trailing spaces
* list elements on the same line are separated with spaces
* hexadecimal literals are lowercase
* file names, function and type names, and global variables have
  the `ngx_` prefix or a more specific prefix such as
  `ngx_http_` and `ngx_mail_`

```c
size_t
ngx_utf8_length(u_char *p, size_t n)
{
    u_char  c, *last;
    size_t  len;

    last = p + n;

    for (len = 0; p < last; len++) {

        c = *p;

        if (c < 0x80) {
            p++;
            continue;
        }

        if (ngx_utf8_decode(&p, last - p) > 0x10ffff) {
            /* invalid UTF-8 */
            return n;
        }
    }

    return len;
}
```



### Files

A typical source file may contain the following sections, separated by
two blank lines:

* copyright statements
* includes
* preprocessor definitions
* type definitions
* function prototypes
* variable definitions
* function definitions

Copyright statements look like this:

```c
/*
 * Copyright (C) Author Name
 * Copyright (C) Organization, Inc.
 */
```

If the file is modified significantly, the list of authors should be updated,
the new author is added to the top.

The `ngx_config.h` and `ngx_core.h` files
are always included first, followed by one of
`ngx_http.h`, `ngx_stream.h`,
or `ngx_mail.h`.
Then follow optional external header files:

```c
#include 
#include 
#include 

#include 
#include 
#include 

#if (NGX_HAVE_EXSLT)
#include 
#endif
```

Header files should include the so-called "header guard":

```c
#ifndef _NGX_PROCESS_CYCLE_H_INCLUDED_
#define _NGX_PROCESS_CYCLE_H_INCLUDED_
...
#endif /* _NGX_PROCESS_CYCLE_H_INCLUDED_ */
```



### Comments

* `//` comments are not used
* text is in English, American spelling is preferred
* multi-line comments are formatted like this:
  ```c
  /*
   * The red-black tree code is based on the algorithm described in
   * the "Introduction to Algorithms" by Cormen, Leiserson and Rivest.
   */
  ```

  ```c
  /* find the server configuration for the address:port */
  ```



### Preprocessor

Macro names start with the `ngx_` or `NGX_`
prefix (or more specific).
Macro names for constants are uppercase.
Parameterized macros and macros for initializers are lowercase.
The macro name and value are separated by at least two spaces:

```c
#define NGX_CONF_BUFFER  4096

#define ngx_buf_in_memory(b)  (b->temporary || b->memory || b->mmap)

#define ngx_buf_size(b)                                                      \
    (ngx_buf_in_memory(b) ? (off_t) (b->last - b->pos):                      \
                            (b->file_last - b->file_pos))

#define ngx_null_string  { 0, NULL }
```

Conditions are inside parentheses, negation is outside:

```c
#if (NGX_HAVE_KQUEUE)
...
#elif ((NGX_HAVE_DEVPOLL && !(NGX_TEST_BUILD_DEVPOLL)) \
       || (NGX_HAVE_EVENTPORT && !(NGX_TEST_BUILD_EVENTPORT)))
...
#elif (NGX_HAVE_EPOLL && !(NGX_TEST_BUILD_EPOLL))
...
#elif (NGX_HAVE_POLL)
...
#else /* select */
...
#endif /* NGX_HAVE_KQUEUE */
```



### Types

Type names end with the `_t` suffix.
A defined type name is separated by at least two spaces:

```c
typedef ngx_uint_t  ngx_rbtree_key_t;
```

Structure types are defined using `typedef`.
Inside structures, member types and names are aligned:

```c
typedef struct {
    size_t      len;
    u_char     *data;
} ngx_str_t;
```

Keep the same alignment between different structures in the file.
A structure that points to itself has a name ending with
`_s`.
Adjacent structure definitions are separated by two blank lines:

```c
typedef struct ngx_list_part_s  ngx_list_part_t;

struct ngx_list_part_s {
    void             *elts;
    ngx_uint_t        nelts;
    ngx_list_part_t  *next;
};


typedef struct {
    ngx_list_part_t  *last;
    ngx_list_part_t   part;
    size_t            size;
    ngx_uint_t        nalloc;
    ngx_pool_t       *pool;
} ngx_list_t;
```

Each structure member is declared on its own line:

```c
typedef struct {
    ngx_uint_t        hash;
    ngx_str_t         key;
    ngx_str_t         value;
    u_char           *lowcase_key;
} ngx_table_elt_t;
```

Function pointers inside structures have defined types ending with
`_pt`:

```c
typedef ssize_t (*ngx_recv_pt)(ngx_connection_t *c, u_char *buf, size_t size);
typedef ssize_t (*ngx_recv_chain_pt)(ngx_connection_t *c, ngx_chain_t *in,
    off_t limit);
typedef ssize_t (*ngx_send_pt)(ngx_connection_t *c, u_char *buf, size_t size);
typedef ngx_chain_t *(*ngx_send_chain_pt)(ngx_connection_t *c, ngx_chain_t *in,
    off_t limit);

typedef struct {
    ngx_recv_pt        recv;
    ngx_recv_chain_pt  recv_chain;
    ngx_recv_pt        udp_recv;
    ngx_send_pt        send;
    ngx_send_pt        udp_send;
    ngx_send_chain_pt  udp_send_chain;
    ngx_send_chain_pt  send_chain;
    ngx_uint_t         flags;
} ngx_os_io_t;
```

Enumerations have types ending with `_e`:

```c
typedef enum {
    ngx_http_fastcgi_st_version = 0,
    ngx_http_fastcgi_st_type,
    ...
    ngx_http_fastcgi_st_padding
} ngx_http_fastcgi_state_e;
```



### Variables

Variables are declared sorted by length of the base type, then alphabetically.
Type names and variable names are aligned.
The type and name "columns" are separated by two spaces.
Large arrays are put at the end of a declaration block:

```c
u_char                      *rv, *p;
ngx_conf_t                  *cf;
ngx_uint_t                   i, j, k;
unsigned int                 len;
struct sockaddr             *sa;
const unsigned char         *data;
ngx_peer_connection_t       *pc;
ngx_http_core_srv_conf_t   **cscfp;
ngx_http_upstream_srv_conf_t *us, *uscf;
u_char                       text[NGX_SOCKADDR_STRLEN];
```

Static and global variables may be initialized on declaration:

```c
static ngx_str_t  ngx_http_memcached_key = ngx_string("memcached_key");
```

```c
static ngx_uint_t  mday[] = { 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 };
```

```c
static uint32_t  ngx_crc32_table16[] = {
    0x00000000, 0x1db71064, 0x3b6e20c8, 0x26d930ac,
    ...
    0x9b64c2b0, 0x86d3d2d4, 0xa00ae278, 0xbdbdf21c
};
```

There is a bunch of commonly used type/name combinations:

```c
u_char                        *rv;
ngx_int_t                      rc;
ngx_conf_t                    *cf;
ngx_connection_t              *c;
ngx_http_request_t            *r;
ngx_peer_connection_t         *pc;
ngx_http_upstream_srv_conf_t  *us, *uscf;
```



### Functions

All functions (even static ones) should have prototypes.
Prototypes include argument names.
Long prototypes are wrapped with a single indentation on continuation lines:

```c
static char *ngx_http_block(ngx_conf_t *cf, ngx_command_t *cmd, void *conf);
static ngx_int_t ngx_http_init_phases(ngx_conf_t *cf,
    ngx_http_core_main_conf_t *cmcf);

static char *ngx_http_merge_servers(ngx_conf_t *cf,
    ngx_http_core_main_conf_t *cmcf, ngx_http_module_t *module,
    ngx_uint_t ctx_index);
```

The function name in a definition starts on a new line.
The opening and closing braces for the function body are on separate lines.
The function body is indented.
There are two empty lines between functions:

```c
static ngx_int_t
ngx_http_find_virtual_server(ngx_http_request_t *r, u_char *host, size_t len)
{
    ...
}


static ngx_int_t
ngx_http_add_addresses(ngx_conf_t *cf, ngx_http_core_srv_conf_t *cscf,
    ngx_http_conf_port_t *port, ngx_http_listen_opt_t *lsopt)
{
    ...
}
```

There is no space after the function name and opening parenthesis.
Long function calls are wrapped so that continuation lines start
at the position of the first function argument.
If this is impossible, format the first continuation line so that it
ends at position 79:

```c
ngx_log_debug2(NGX_LOG_DEBUG_HTTP, r->connection->log, 0,
               "http header: \"%V: %V\"",
               &h->key, &h->value);

hc->busy = ngx_palloc(r->connection->pool,
                  cscf->large_client_header_buffers.num * sizeof(ngx_buf_t *));
```

The `ngx_inline` macro should be used instead of
`inline`:

```c
static ngx_inline void ngx_cpuid(uint32_t i, uint32_t *buf);
```



### Expressions

Binary operators except `.` and `->`
should be separated from their operands by one space.
Unary operators and subscripts are not separated from their operands by spaces:

```c
width = width * 10 + (*fmt++ - '0');
```

```c
ch = (u_char) ((decoded << 4) + (ch - '0'));
```

```c
r->exten.data = &r->uri.data[i + 1];
```

Type casts are separated by one space from casted expressions.
An asterisk inside a type cast is separated by a space from the type name:

```c
len = ngx_sock_ntop((struct sockaddr *) sin6, p, len, 1);
```

If an expression does not fit into a single line, it is wrapped.
The preferred point to break a line is a binary operator.
The continuation line is aligned with the start of expression:

```c
if (status == NGX_HTTP_MOVED_PERMANENTLY
    || status == NGX_HTTP_MOVED_TEMPORARILY
    || status == NGX_HTTP_SEE_OTHER
    || status == NGX_HTTP_TEMPORARY_REDIRECT
    || status == NGX_HTTP_PERMANENT_REDIRECT)
{
    ...
}
```

```c
p->temp_file->warn = "an upstream response is buffered "
                     "to a temporary file";
```

As a last resort, it is possible to wrap an expression so that
the continuation line ends at position 79:

```c
hinit->hash = ngx_pcalloc(hinit->pool, sizeof(ngx_hash_wildcard_t)
                                     + size * sizeof(ngx_hash_elt_t *));
```

The above rules also apply to sub-expressions,
where each sub-expression has its own indentation level:

```c
if (((u->conf->cache_use_stale & NGX_HTTP_UPSTREAM_FT_UPDATING)
     || c->stale_updating) && !r->background
    && u->conf->cache_background_update)
{
    ...
}
```

Sometimes it is convenient to wrap an expression after a type cast.
In this case, the continuation line is indented:

```c
node = (ngx_rbtree_node_t *)
           ((u_char *) lr - offsetof(ngx_rbtree_node_t, color));
```

Pointers are explicitly compared with
`NULL` (not `0`):

```c
if (ptr != NULL) {
    ...
}
```



### Conditionals and Loops

The `if` keyword is separated from the condition
by one space.
The opening brace is located on the same line, or on a
dedicated line if the condition takes several lines.
The closing brace is located on a dedicated line, optionally followed by
`else if` / `else`.
Usually, there is an empty line before the
`else if` / `else` part:

```c
if (node->left == sentinel) {
    temp = node->right;
    subst = node;

} else if (node->right == sentinel) {
    temp = node->left;
    subst = node;

} else {
    subst = ngx_rbtree_min(node->right, sentinel);

    if (subst->left != sentinel) {
        temp = subst->left;

    } else {
        temp = subst->right;
    }
}
```

Similar formatting rules apply to `do` and
`while` loops:

```c
while (p < last && *p == ' ') {
    p++;
}
```

```c
do {
    ctx->node = rn;
    ctx = ctx->next;
} while (ctx);
```

The `switch` keyword is separated from the condition
by one space.
The opening brace is located on the same line.
The closing brace is located on a dedicated line.
The `case` keywords are aligned with
`switch`:

```c
switch (ch) {
case '!':
    looked = 2;
    state = ssi_comment0_state;
    break;

case '<':
    copy_end = p;
    break;

default:
    copy_end = p;
    looked = 0;
    state = ssi_start_state;
    break;
}
```

Most `for` loops are formatted as follows:

```c
for (i = 0; i < ccf->env.nelts; i++) {
    ...
}
```

```c
for (q = ngx_queue_head(locations);
     q != ngx_queue_sentinel(locations);
     q = ngx_queue_next(q))
{
    ...
}
```

If some part of the `for` statement is omitted,
this is indicated by the `/* void */` comment:

```c
for (i = 0; /* void */ ; i++) {
    ...
}
```

A loop with an empty body is also indicated by the
`/* void */` comment which may be placed on the same line:

```c
for (cl = *busy; cl->next; cl = cl->next) { /* void */ }
```

An endless loop looks like this:

```c
for ( ;; ) {
    ...
}
```



### Labels

Labels are surrounded by empty lines and are indented at the previous level:

```c
    if (i == 0) {
        u->err = "host not found";
        goto failed;
    }

    u->addrs = ngx_pcalloc(pool, i * sizeof(ngx_addr_t));
    if (u->addrs == NULL) {
        goto failed;
    }

    u->naddrs = i;

    ...

    return NGX_OK;

failed:

    freeaddrinfo(res);
    return NGX_ERROR;
```



## Debugging Memory Issues

To debug memory issues such as buffer overruns or use-after-free errors, you
can use [AddressSanitizer](https://en.wikipedia.org/wiki/AddressSanitizer)
(ASan), supported by some modern compilers.
To enable ASan with `gcc` and `clang`,
use the `-fsanitize=address` compiler and linker option.
When building Angie, this can be done by adding the option to
`--with-cc-opt` and `--with-ld-opt` parameters
of the `configure` script.

Since most allocations in Angie are made from Angie internal
[pool](#pool), enabling ASan may not always be enough to debug
memory issues.
The internal pool allocates a big chunk of memory from the system and cuts
smaller allocations from it.
However, this mechanism can be disabled by setting the
`NGX_DEBUG_PALLOC` macro to `1`.
In this case, allocations are passed directly to the system allocator, giving it
full control over buffer boundaries.

The following configuration line summarizes the information provided above.
It is recommended while developing third-party modules and testing Angie on
different platforms.

```bash
auto/configure --with-cc-opt='-fsanitize=address -DNGX_DEBUG_PALLOC=1'
               --with-ld-opt=-fsanitize=address
```



## Common Pitfalls



### Writing a C module

The most common pitfall is an attempt to write a full-fledged C module
when it can be avoided.
In most cases your task can be accomplished by creating a proper configuration.
If writing a module is inevitable, try to make it
as small and simple as possible.
For example, a module can only export some
[variables](#http_variables).

Before starting a module, consider the following questions:

* Is it possible to implement a desired feature using already
  [available modules](https://en.angie.software//angie/docs/configuration/modules/index.md#modules)?
* Is it possible to solve an issue using built-in scripting languages,
  such as [Perl](https://en.angie.software//angie/docs/configuration/modules/http/http_perl.md#http-perl) or [NJS](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs)?



### C Strings

The most used string type in Angie,
[ngx_str_t](#string_overview) is not a C-style
zero-terminated string.
You cannot pass the data to standard C library functions
such as `strlen()` or `strstr()`.
Instead, Angie [counterparts](#string_overview)
that accept either `ngx_str_t` should be used
or pointer to data and a length.
However, there is a case when `ngx_str_t` holds
a pointer to a zero-terminated string: strings that come as a result of
configuration file parsing are zero-terminated.



### Global Variables

Avoid using global variables in your modules.
Most likely it is an error to have a global variable.
Any global data should be tied to a [configuration cycle](#cycle)
and be allocated from the corresponding [memory pool](#pool).
This allows Angie to perform graceful configuration reloads.
An attempt to use global variables will likely break this feature,
because it will be impossible to have two configurations at
the same time and get rid of them.
Sometimes global variables are required.
In this case, special attention is needed to manage reconfiguration
properly.
Also, check if libraries used by your code have implicit
global state that may be broken on reload.



### Manual Memory Management

Instead of dealing with malloc/free approach which is error prone,
learn how to use Angie [pools](#pool).
A pool is created and tied to an object -
[configuration](#http_conf),
[cycle](#cycle),
connection <#http_connection>,
or [HTTP request](#http_request).
When the object is destroyed, the associated pool is destroyed too.
So when working with an object, it is possible to allocate the amount
needed from the corresponding pool and not worry about freeing memory
even in case of errors.



### Threads

It is recommended to avoid using threads in Angie because it will
definitely break things: most Angie functions are not thread-safe.
It is expected that a thread will be executing only system calls and
thread-safe library functions.
If you need to run some code that is not related to client request processing,
the proper way is to schedule a timer in the `init_process`
module handler and perform required actions in timer handler.
Internally Angie makes use of [threads](#dev_threads) to
boost IO-related operations, but this is a special case with a lot
of limitations.



### Blocking Libraries

A common mistake is to use libraries that are blocking internally.
Most libraries out there are synchronous and blocking by nature.
In other words, they perform one operation at a time and waste
time waiting for response from other peer.
As a result, when a request is processed with such library, whole
Angie worker is blocked, thus destroying performance.
Use only libraries that provide asynchronous interface and don't
block whole process.



### HTTP Requests to External Services

Often modules need to perform an HTTP call to some external service.
A common mistake is to use some external library, such as libcurl,
to perform the HTTP request.
It is absolutely unnecessary to bring a huge amount of external
(probably [blocking](#using_libraries)!) code
for the task which can be accomplished by Angie itself.

There are two basic usage scenarios when an external request is needed:

* in the context of processing a client request (for example, in content handler)
* in the context of a worker process (for example, timer handler)

In the first case, the best is to use
[subrequests API](#http_subrequests).
Instead of directly accessing external service, you declare a location
in Angie configuration and direct your subrequest to this location.
This location is not limited to
[proxying](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass)
requests, but may contain other Angie directives.
An example of such approach is the
[auth_request](https://en.angie.software//angie/docs/configuration/modules/http/http_auth_request.md#id1) directive implemented in
[Auth Request](https://en.angie.software//angie/docs/configuration/modules/http/http_auth_request.md#http-auth-request).

For the second case, it is possible to use basic HTTP client functionality
available in Angie.
For example,
[OCSP module](https://github.com/nginx/nginx/blob/master/src/event/ngx_event_openssl_stapling.c)
implements simple HTTP client.


# https://en.angie.software/angie/docs/oss_changes.md





# Angie Version History

## 2026



### Angie 1.12.1

Release date: 17.07.2026.



#### Security

- When evaluating a string expression in which unnamed capture variables
  (`$1`, `$2`, etc.) preceded a [map](https://en.angie.software//angie/docs/configuration/modules/http/http_map.md#id1) directive
  variable whose value is determined by a regular expression, or when using a
  non-cacheable (`volatile`) [map](https://en.angie.software//angie/docs/configuration/modules/http/http_map.md#id1) directive variable whose
  key contained a capture variable also used in the value of the same
  directive, worker process memory corruption or a worker process crash could
  occur ([CVE-2026-42533](https://nvd.nist.gov/vuln/detail/CVE-2026-42533)); the fix was ported from
  nginx 1.31.3.
- When using the [slice](https://en.angie.software//angie/docs/configuration/modules/http/http_slice.md#id1) directive or
  [background cache update](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-background-update), if unnamed
  capture variables (`$1`, `$2`, etc.) were used together with a
  non-cacheable (`volatile`) [map](https://en.angie.software//angie/docs/configuration/modules/http/http_map.md#id1) directive variable with a
  regular expression, the value of an unnamed capture variable could contain
  arbitrary bytes from worker process memory, or a worker process crash could
  occur ([CVE-2026-60005](https://nvd.nist.gov/vuln/detail/CVE-2026-60005)); the fix was ported from
  nginx 1.31.3.
- When using the [SSI](https://en.angie.software//angie/docs/configuration/modules/http/http_ssi.md#http-ssi) module with unbuffered proxying, worker
  process memory corruption or a worker process crash could occur
  ([CVE-2026-56434](https://nvd.nist.gov/vuln/detail/CVE-2026-56434)); the
  fix was ported from nginx 1.31.3.



#### Bugfixes

- In certain cases when using the [Metric](https://en.angie.software//angie/docs/configuration/modules/http/http_metric.md#http-metric) module, metric
  data corruption could occur; in `expire=on` mode, this could also
  cause a worker process crash.
- When using the [least_time](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-least-time) directive with the
  [zone](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone) directive, proxying to such a group with all servers
  unavailable could cause the worker process to enter an infinite loop.



#### Packages

- Updated:
  - [angie-module-auth-jwt](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-jwt.md#external-auth-jwt), to version 0.14.2



### Angie 1.12.0

Release date: 13.07.2026.



#### Features

- Load balancing based on the average time to receive the response header or
  the full response from proxied HTTP servers, with a configurable smoothing
  factor, using the [least_time](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-least-time) directive in the
  `upstream` block; the feature was ported from Angie PRO.
- Load balancing based on the average time to establish a connection and
  receive the first or last byte of the response from proxied stream servers,
  with a configurable smoothing factor, using the
  [least_time](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-least-time) directive in the `upstream` block;
  the feature was ported from Angie PRO.
- The `learn` mode of the [sticky](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky) directive for binding
  sessions to proxied servers, which allows detecting sessions and storing them
  in the server's shared memory; the feature was ported from Angie PRO.
- The `drain` mode, which puts a proxied server into the new
  `draining` state, where only requests bound via
  [sticky](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky) are directed to that server; the feature was ported
  from Angie PRO.
- Average time to receive the HTTP response header and the full response in the
  `/status/http/upstreams/` statistics API section for each proxied
  server, with the ability to configure the smoothing factor using the
  [response_time_factor](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-response-time-factor) directive in the
  `upstream` block, and Prometheus support; the feature was ported from
  Angie PRO.
- Average time to establish a connection and receive the first and last byte
  in the `/status/stream/upstreams/` statistics API section for each
  proxied stream server, with the ability to configure the smoothing factor
  using the [response_time_factor](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-response-time-factor) directive in
  the `upstream` block, and Prometheus support; the feature was ported
  from Angie PRO.
- The [Metric](https://en.angie.software//angie/docs/configuration/modules/stream/stream_metric.md#stream-metric) module for stream enabling arbitrarily
  configurable statistics collection; allows aggregating any
  connection-processing data at any stage in real time using variables grouped
  by custom keys, with various methods (counters, histograms, moving averages,
  etc.), and exposes them via the `/status/stream/metric_zones/`
  statistics API section (with Prometheus support).
- Information about certificates defined in the configuration, as well as those
  obtained by ACME clients, in the [/certificates/](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#certificates)
  statistics API section; allows easy monitoring of certificates loaded in the
  configuration.
- Obtaining certificates for IP addresses using ACME.
- Support for ACME profiles using the new `profile` parameter of the
  [acme_client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) directive; used in particular for requesting
  certificates for IP addresses in Let's Encrypt.
- Support for External Account Binding (EAB), which allows linking an ACME
  account with an external account at the certificate authority using HMAC
  authentication; required by some commercial certificate authorities.
- Enhanced compatibility with servers that do not strictly comply with the ACME
  protocol, particularly SSL.com.
- The [acme_dns_ttl](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-dns-ttl) directive that allows changing the TTL
  value in DNS query responses during domain verification for ACME; some
  providers filter DNS responses with a low TTL.
- Automatic retrieval of DNS server addresses from a file in
  `resolv.conf` format using the `conf` parameter of the
  [resolver](https://en.angie.software//angie/docs/configuration/modules/http/index.md#resolver) directive; the file is re-read when it changes,
  which simplifies configuration and eliminates the need to manually specify
  server addresses in the configuration.
- New [DoH](https://en.angie.software//angie/docs/configuration/modules/http/http_doh.md#http-doh) HTTP module implementing a DNS over HTTPS server
  (RFC 8484) that accepts DNS queries over HTTP/HTTPS and proxies them to DNS
  server groups via UDP or TCP.
- The Docker network in which container IP addresses are looked up can now be
  specified via an individual [Docker](https://en.angie.software//angie/docs/configuration/modules/http/http_docker.md#http-docker) label for each
  specific upstream group.
- The [goto](https://en.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#goto) directive in the rewrite module performs an internal
  redirect to a named location without modifying the URI; supports conditional
  execution inside an `if` block; replaces common workarounds based on
  `try_files` with a guaranteed-nonexistent path or `error_page`
  with `return` and an otherwise-unused status code.
- Log message filtering using the `filter=` parameter of the
  [error_log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log) directive, and the new
  [error_log_user_tag](https://en.angie.software//angie/docs/configuration/modules/http/index.md#error-log-user-tag) directive for adding tags that
  can then be used in filter conditions; allows flexible log configuration for
  tracking unique events on the server with the ability to attach various
  handlers to them.
- The `format=` parameter of the [error_log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log) directive,
  which allows switching the log message format to JSON.
- Limiting the maximum error logging rate using the `rate` parameter of
  the [error_log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log) directive; the default limit is 1000
  messages per second.
  Thanks to Maxim Dounin (freenginx).
- The [time_format](https://en.angie.software//angie/docs/configuration/modules/http/index.md#time-format) directive allows defining a variable
  with a custom time format, supporting strftime()-like specifiers as well as
  `%L` for milliseconds.
- Reduced CPU usage when using the [status_zone](https://en.angie.software//angie/docs/configuration/modules/http/index.md#status-zone) directive
  with variables in the HTTP and stream modules under high load.
- Built-in HTML error pages and the directory listing page of the
  [AutoIndex](https://en.angie.software//angie/docs/configuration/modules/http/http_autoindex.md#http-autoindex) module now support a dark color scheme
  following the user's OS-level preference.
- The new `$upstream_transport` variable exposes the transport protocol
  (TCP or UDP) used for each upstream connection attempt; values for multiple
  attempts are separated by a comma.
- The [ssl_keylog_file](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-keylog-file) and
  [proxy_ssl_keylog_file](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ssl-keylog-file) directives specify the
  file to log SSL session keys.
- All functionality of nginx 1.31.2, including the new
  [Tunnel](https://en.angie.software//angie/docs/configuration/modules/http/http_tunnel.md#http-tunnel) HTTP module for CONNECT tunneling and HTTP/2
  support for connections to proxied servers; the
  [keepalive](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive) directive in the `upstream` block is
  left disabled, as its use may lead to unexpected consequences in some
  scenarios that are not addressed by the proposed `local` option.



#### Changes

- In the HTTP and stream modules, the `resolver conf` directive is now
  set by default, using DNS servers from `/etc/resolv.conf`; to
  explicitly disable DNS resolution, as was previously the case when no
  [resolver](https://en.angie.software//angie/docs/configuration/modules/http/index.md#resolver) directive was present in the configuration, the
  new `off` parameter can be used.



#### Bugfixes

- If `$metric_*` or `$metric_*_key` variables were set
  sequentially for multiple metric zones within a single request, updating
  statistics or retrieving related variables used the key of the last specified
  zone.
- The `$metric_*` variable returned the specified string, not the key
  along with the calculated metric value. The `$metric_*_value` variable
  had to be used in order to get the actual value.
- A key used for statistics calculation in the [Metric](https://en.angie.software//angie/docs/configuration/modules/http/http_metric.md#http-metric)
  module could be truncated if it was specified together with a value and
  contained the `=` character.
- The [proxy_no_cache](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-no-cache) directive was not checked when
  caching errors.
  Thanks to Maxim Dounin (freenginx).
- Using the [add_header](https://en.angie.software//angie/docs/configuration/modules/http/http_headers.md#add-header) directive for `Content-Type`
  might result in the addition of another `Content-Type` field in the
  response header.
- The [ACME](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme) module was not functional with `select`
  and `poll` event processing methods.



#### Packages

- Updated:
  - [angie-module-lua](https://en.angie.software//angie/docs/configuration/modules/external-modules/lua.md#external-lua), to version 0.10.31 / v0.0.17
  - [angie-module-njs](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs), to version 1.0.0
  - [angie-module-opentracing](https://en.angie.software//angie/docs/configuration/modules/external-modules/opentracing.md#external-opentracing), to version 0.48.0
  - [angie-module-vod](https://en.angie.software//angie/docs/configuration/modules/external-modules/vod.md#external-vod), to version 1.9.0



### Angie 1.11.8

Release date: 18.06.2026.



#### Security

- When proxying a specially crafted request to a gRPC backend with the
  [ignore_invalid_headers](https://en.angie.software//angie/docs/configuration/modules/http/index.md#ignore-invalid-headers) directive set to `off` and the
  [large_client_header_buffers](https://en.angie.software//angie/docs/configuration/modules/http/index.md#large-client-header-buffers) directive with a large value, a buffer
  overflow could occur, allowing an attacker to corrupt the worker process
  memory or cause its crash
  ([CVE-2026-42055](https://nvd.nist.gov/vuln/detail/CVE-2026-42055));
  the fix was ported from nginx 1.31.2.
- When processing a specially crafted response with UTF-8 decoding via the
  [charset_map](https://en.angie.software//angie/docs/configuration/modules/http/http_charset.md#charset-map) directive, an out-of-bounds read could occur, allowing an
  attacker to send limited worker process memory contents to the client or
  cause its crash
  ([CVE-2026-48142](https://nvd.nist.gov/vuln/detail/CVE-2026-48142));
  the fix was ported from nginx 1.31.2.



#### Bugfixes

- An IP address without a port number in the [acme_http_port](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-http-port) or
  [acme_dns_port](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-dns-port) directives caused a master process crash when reading
  the configuration.



#### Packages

- Updated:
  - [angie-module-keyval](https://en.angie.software//angie/docs/configuration/modules/external-modules/keyval.md#external-keyval), to version 0.5.0



### Angie 1.11.7

Release date: 15.06.2026.



#### Features

- Compatibility with OpenSSL 4.0.



#### Bugfixes

- In some configurations, the response to an ACME DNS challenge could be
  sent from a different IP address/interface than the one the request was
  received on, which could result in a certificate issuance failure.
- When using the [Docker](https://en.angie.software//angie/docs/configuration/modules/http/http_docker.md#http-docker) module, rapid termination of
  containers immediately after start could cause a worker process crash.
- Changing parameters in the [metric_zone](https://en.angie.software//angie/docs/configuration/modules/http/http_metric.md#metric-zone) or
  [metric_complex_zone](https://en.angie.software//angie/docs/configuration/modules/http/http_metric.md#metric-complex-zone) directives for an already
  existing zone could cause a worker process crash on configuration reload.
- When using the `window=` parameter of the `average mean`
  metric, the result could be calculated incorrectly on some intervals; in
  particular, shortly after system startup on Linux, the values could remain
  zero.
- The values of `count` and `histogram` metrics were output
  incorrectly on 32-bit platforms after reaching 2^32-1.
- The build failed when the `./configure` option
  `--with-stream=dynamic` was combined with
  `--with-stream_acme_module`; the bug had appeared in 1.10.3.



#### Packages

- Updated:
  - [angie-module-auth-jwt](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-jwt.md#external-auth-jwt), to version 0.14.1
  - [angie-module-opentracing](https://en.angie.software//angie/docs/configuration/modules/external-modules/opentracing.md#external-opentracing), to version v0.47.0
  - [angie-module-vod](https://en.angie.software//angie/docs/configuration/modules/external-modules/vod.md#external-vod), to version v1.8.1



### Angie 1.11.6

Release date: 25.05.2026.



#### Security

- When using the [rewrite](https://en.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#id5) directive with a regex containing nested
  PCRE captures and a replacement string referencing multiple such
  captures, an attacker, given conditions beyond the attacker's control,
  could cause a worker process crash, or, on systems without address
  space layout randomization, arbitrary code execution
  ([CVE-2026-9256](https://nvd.nist.gov/vuln/detail/CVE-2026-9256));
  the fix was ported from nginx 1.31.1.



#### Packages

- Updated:
  - [angie-module-auth-jwt](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-jwt.md#external-auth-jwt), to version 0.13.1
  - [angie-module-njs](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs), to version 0.9.9
  - [angie-module-testcookie](https://en.angie.software//angie/docs/configuration/modules/external-modules/testcookie.md#external-testcookie), to version 7d263d4
  - [angie-module-vod](https://en.angie.software//angie/docs/configuration/modules/external-modules/vod.md#external-vod), to version v1.7.2



### Angie 1.11.5

Release date: 15.05.2026.



#### Security

- When the [rewrite](https://en.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#id5) directive with an unnamed capture (e.g.,
  `$1`, `$2`) and a replacement string containing `?` was followed by a
  [rewrite](https://en.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#id5), [if](https://en.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#if), or [set](https://en.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#set) directive, an attacker, given conditions
  beyond the attacker's control, could cause a worker process crash
  and, on systems without address space layout randomization, arbitrary
  code execution
  ([CVE-2026-42945](https://nvd.nist.gov/vuln/detail/CVE-2026-42945));
  the fix was ported from nginx 1.31.0.
- When using the [ssl_ocsp](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-ocsp) directive, a use of previously
  freed memory could occur while processing DNS server responses,
  allowing an attacker to corrupt the worker process memory or cause
  its crash
  ([CVE-2026-40701](https://nvd.nist.gov/vuln/detail/CVE-2026-40701));
  the fix was ported from nginx 1.31.0.
- When using HTTP/3, an attacker could spoof the IP address
  and thereby bypass restrictions or authorization in some
  configurations
  ([CVE-2026-40460](https://nvd.nist.gov/vuln/detail/CVE-2026-40460));
  the fix was ported from nginx 1.31.0.
- When [scgi_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-pass) or [uwsgi_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-pass) was configured, an
  attacker in a man-in-the-middle (MITM) position, controlling
  responses from a proxied server, could cause excessive memory
  allocation or an over-read of data, leading to the disclosure of
  worker process memory to the client or a process crash
  ([CVE-2026-42946](https://nvd.nist.gov/vuln/detail/CVE-2026-42946));
  the fix was ported from nginx 1.31.0.
- When processing a specially crafted response with UTF-8
  decoding via the [charset_map](https://en.angie.software//angie/docs/configuration/modules/http/http_charset.md#charset-map) directive, an out-of-bounds read could
  occur in the worker process, allowing an attacker, given conditions
  beyond the attacker's control, to send limited worker process memory
  contents to the client or cause process crash
  ([CVE-2026-42934](https://nvd.nist.gov/vuln/detail/CVE-2026-42934));
  the fix was ported from nginx 1.31.0.



#### Packages

- Updated:
  - [angie-module-auth-totp](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-totp.md#external-auth-totp), to version 1.2.0
  - [angie-module-cache-purge](https://en.angie.software//angie/docs/configuration/modules/external-modules/cache-purge.md#external-cache-purge), to version 3.0.2
  - [angie-module-keyval](https://en.angie.software//angie/docs/configuration/modules/external-modules/keyval.md#external-keyval), to version 0.4.0
  - [angie-module-njs](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs), to version 0.9.8
  - [angie-module-opentracing](https://en.angie.software//angie/docs/configuration/modules/external-modules/opentracing.md#external-opentracing), to version v0.46.0
- Switched source of [angie-module-dav-ext](https://en.angie.software//angie/docs/configuration/modules/external-modules/dav-ext.md#external-dav-ext) to
  [mid1221213/nginx-dav-ext-module](https://github.com/mid1221213/nginx-dav-ext-module) v4.0.1.
- Switched source of [angie-module-vod](https://en.angie.software//angie/docs/configuration/modules/external-modules/vod.md#external-vod) to
  [dio-az/nginx-vod-module](https://github.com/dio-az/nginx-vod-module) v1.7.1.



### Angie 1.11.4

Release date: 25.03.2026.



#### Security

- TLS handshake with a client in the [Stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) module might
  succeed despite OCSP rejecting the client certificate
  ([CVE-2026-28755](https://nvd.nist.gov/vuln/detail/CVE-2026-28755));
  the fix was ported from nginx 1.29.7.
- A buffer overflow might occur in the DAV module while
  handling a COPY or MOVE request in a `location` with the [alias](https://en.angie.software//angie/docs/configuration/modules/http/index.md#alias)
  directive, allowing an attacker to modify the source or destination
  path outside of the document root directory
  ([CVE-2026-27654](https://nvd.nist.gov/vuln/detail/CVE-2026-27654));
  the fix was ported from nginx 1.29.7.
- Processing of a specially crafted file by the MP4 module on
  32-bit platforms might cause a worker process crash, or might have
  potential other impact
  ([CVE-2026-27784](https://nvd.nist.gov/vuln/detail/CVE-2026-27784));
  the fix was ported from nginx 1.29.7.
- Processing of a specially crafted file by the MP4 module
  might cause a worker process crash, or might have potential other
  impact
  ([CVE-2026-32647](https://nvd.nist.gov/vuln/detail/CVE-2026-32647));
  the fix was ported from nginx 1.29.7.
- If the CRAM-MD5 or APOP authentication methods were used in
  the [Mail](https://en.angie.software//angie/docs/configuration/modules/mail/index.md#mail-core) proxy module and authentication retry was enabled,
  then a worker process could crash
  ([CVE-2026-27651](https://nvd.nist.gov/vuln/detail/CVE-2026-27651));
  the fix was ported from nginx 1.29.7.
- When the [Mail](https://en.angie.software//angie/docs/configuration/modules/mail/index.md#mail-core) proxy module was used, an attacker using PTR
  DNS records could inject data in authentication HTTP requests, as
  well as in the XCLIENT command in the SMTP connection to the proxied
  server
  ([CVE-2026-28753](https://nvd.nist.gov/vuln/detail/CVE-2026-28753));
  the fix was ported from nginx 1.29.7.



#### Bugfixes

- Rare system errors before the connection to the proxied
  server might affect the peer status correctness in [HTTP](https://en.angie.software//angie/docs/configuration/modules/index.md#modules-http)
  and [Stream](https://en.angie.software//angie/docs/configuration/modules/index.md#modules-stream) modules; they might also lead to the crash
  of a worker process in the [Stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) module;
  the bug had appeared in 1.9.1.
- In configurations where the [proxy_http_version](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http-version) `3` and
  [proxy_set_header](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-set-header) `Host ..` directives were inherited from the
  `http` block, outgoing HTTP/3 requests might be sent without the
  `Host` header.



#### Packages

- Updated:
  - [angie-module-auth-jwt](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-jwt.md#external-auth-jwt), to version 0.11.0
  - [angie-module-cache-purge](https://en.angie.software//angie/docs/configuration/modules/external-modules/cache-purge.md#external-cache-purge), to version 2.5.6
  - [angie-module-cgi](https://en.angie.software//angie/docs/configuration/modules/external-modules/cgi.md#external-cgi), to version v0.15
  - [angie-module-njs](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs), to version 0.9.6
  - [angie-module-opentracing](https://en.angie.software//angie/docs/configuration/modules/external-modules/opentracing.md#external-opentracing), to version v0.43.0



### Angie 1.11.3

Release date: 06.02.2026.



#### Security

- An attacker in a man-in-the-middle (MITM) position before a proxied server
  using TLS, given conditions beyond the attacker's control, could inject
  plaintext data into the response before the TLS handshake begins
  ([CVE-2026-1642](https://nvd.nist.gov/vuln/detail/CVE-2026-1642));
  the fix was ported from nginx 1.29.5.



#### Packages

- Updated:
  - [angie-module-jwt](https://en.angie.software//angie/docs/configuration/modules/external-modules/jwt.md#external-jwt), to version 3.4.4



### Angie 1.11.2

Release date: 15.01.2026.



#### Bugfixes

- If BPF was disabled, HTTP/3 requests might fail with an error
  `[alert] sendmsg() failed (90: Message too large) while sending frames`;
  the bug had appeared in 1.11.0.
- HTTP/3 requests were not accepted when listening on an IPv6
  wildcard address with BPF enabled;
  the bug had appeared in 1.11.0.
- When a domain name was specified in the [docker_endpoint](https://en.angie.software//angie/docs/configuration/modules/http/http_docker.md#docker-endpoint) directive,
  connections to the Docker API and updates of the upstream server
  groups didn't occur.



#### Packages

- Updated:
  - [angie-module-cache-purge](https://en.angie.software//angie/docs/configuration/modules/external-modules/cache-purge.md#external-cache-purge) to version 2.5.5

02.02.2026

- Updated:
  - [angie-module-njs](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs), to version 0.9.5

## 2025



### Angie 1.11.1

Release date: 30.12.2025.



#### Changes

- Now, if only port without IP is specified (default value) in
  the [acme_http_port](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-http-port) directive and there are
  `server` blocks listening on that port, HTTP challenge handling
  for the port in ACME is working only on the IP addresses configured in
  the [listen](https://en.angie.software//angie/docs/configuration/modules/http/index.md#listen) directives of these blocks; there will be no attempt
  to listen on all IP addresses, like it was before; this makes
  configuration more flexible and prevents the issue with updating from
  previous versions with configurations where there were only
  `server` blocks listening on port `80` and particular IP
  addresses.



#### Bugfixes

- HTTP/2 requests were not counted in server zone statistics;
  the bug had appeared in 1.11.0.
- When an ACME client was disabled in the configuration and had
  no previously obtained certificate, a statistics API request for that
  client could crash a worker process.
- If the `$http_host` or `$cookie_*` variables were used as
  keys in the [status_zone](https://en.angie.software//angie/docs/configuration/modules/http/index.md#status-zone) directive within the `server`
  block, HTTP/3 requests might not be counted in this status zone.



#### Packages

- Updated:
  - [angie-module-vts](https://en.angie.software//angie/docs/configuration/modules/external-modules/vts.md#external-vts), to version v0.2.5



### Angie 1.11.0

Release date: 24.12.2025.



#### Changes

- The `$http_host` variable in HTTP/3 requests is now
  initialized from the value of the `:authority` pseudo-header if the
  `Host` header was not passed, which is normal for clients;
  previously, differences from earlier protocol versions might cause
  issues in configurations with `$http_host`.
- If all HTTP servers in an `upstream` group are unavailable or
  returning an error, the own error page is now always returned instead
  of the response from the last server when receiving a status
  considered an error according to the
  [proxy_next_upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-next-upstream) directive
  (and similar); this ensures consistent behavior in all cases.
- The `REQUEST_METHOD` parameter in `fastcgi.conf`,
  `fastcgi_params`, `uwsgi_params`, and `scgi_params`
  configuration files now is set via the `$upstream_request_method` variable, which
  takes the value `GET` for `HEAD` requests when caching is configured;
  this prevents an issue where a `HEAD` request could previously result
  in storing an empty response, which would then be served for `GET`
  requests, since the request method is not a part of the cache key in
  common configurations.
- The maximum response size from the ACME server is now limited
  by the [acme_max_response_size](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-max-response-size) directive instead of the
  `max_cert_size=` parameter of the [acme_client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) directive; the
  default value is enough for most cases, but if a certificate update
  ends up with the `[error] too big subrequest response while sending
  to client` error message, its value should be increased.
- The default value of the [variables_hash_max_size](https://en.angie.software//angie/docs/configuration/modules/http/index.md#variables-hash-max-size) directive
  in the HTTP module was increased to `2048` in order to reduce
  possibility of a warning about suboptimal hash build due to new
  variables added during the recent years: `[warn] could not build
  optimal variables_hash, you should increase either
  variables_hash_max_size: 1024 or variables_hash_bucket_size: 64;
  ignoring variables_hash_bucket_size`.



#### Features

- The new [Metric](https://en.angie.software//angie/docs/configuration/modules/http/http_metric.md#http-metric) module enabling arbitrary, real‑time HTTP
  metrics collection with fully configurable aggregation methods
  (counters, histograms, moving averages, etc.); it allows tracking any
  request‑processing data at any stage, grouped by custom keys, and
  exposes the metrics via the `/status/http/metric_zones/` API section
  (including Prometheus support), providing a powerful built‑in
  analytics tool for the entire HTTP traffic.
- Support for ALPN validation for ACME, enabled by specifying
  `alpn` in the `challenge` parameter of the
  [acme_client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) directive;
  allows to request multi-domain certificates while keeping only the
  HTTPS port open.
- Information on ACME clients and certificate requesting
  procedure in the `/status/http/acme_clients/` section of the
  statistics API (with Prometheus support).
- Added support for Encrypted Client Hello (ECH) in HTTP and
  stream SSL modules; the new [ssl_encrypted_hello_key](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-encrypted-hello-key) directive
  specifies the file with the private key; the `$ssl_encrypted_hello`
  variable contains information about ECH usage.
  Thanks to Maxim Dounin (freenginx).
- Conversion of the image format using the `convert` parameter
  for the [image_filter](https://en.angie.software//angie/docs/configuration/modules/http/http_image_filter.md#id1) directive.
- Support for AVIF and HEIC formats in the Image Filter
  module.
- Support for PROXY protocol V2 with upstream server
  connections in the stream module and the ability to set arbitrary TLV
  values using the [proxy_protocol_tlv](https://en.angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-protocol-tlv) directive which allows a string
  with variables.
- The `$upstream_request_method` variable that contains the
  upstream request method, which can be different from the client
  request method when caching is enabled or the
  [proxy_method](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-method) is set;
  this helps avoid the common configuration issue where a cached empty
  `HEAD` response is served for `GET` requests, as well as avoid caching
  `HEAD` and `GET` responses separately.
- Removed the need to define a separate `server` block with a
  `listen 80` directive for ACME HTTP challenges; the listening port
  can be customized using the [acme_http_port](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-http-port) directive if
  necessary.
- Ability to count the number of items in lists and objects
  when exporting Prometheus metrics; paths ending with a trailing slash
  now return the count of items in the corresponding API collection.
- The `$sent_body` variable containing the response body of a
  subrequest or external request by client module.
- XOAUTH2 and OAUTHBEARER authentication mechanisms support in
  the mail proxy module.
  Thanks to Rob Mueller and Maxim Dounin (freenginx).
- The `route` parameter of the [sticky](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky) directive may now
  include arbitrary strings with any number of variables.
- In the ACME module, the approximate size of a renewed
  certificate is now calculated automatically, eliminating the need to
  increase the `max_cert_size` parameter of the
  [acme_client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) directive
  when issuing a certificate with a very large number of domains; the
  parameter is retained for cases where manual configuration is still
  required.
- The `$upstream_cache_key` variable that contains the cache
  key being used.
  Thanks to Kirill A. Korinsky and Maxim Dounin (freenginx).
- Support for building with AWS-LC SSL library.
  Thanks to Piotr Sikora (piotr at aviatrix.com).
- The new Makefile target `test` executing the test suite.
- All functionality of nginx 1.29.3 except the
  `add_header_inherit` and `add_trailer_inherit` directives, which are
  omitted due to their poor design.



#### Bugfixes

- Reload and binary upgrade procedures are now working
  correctly with HTTP/3 connections; connections are properly routed to
  all existing processes using the BPF module.
- If all servers in an `upstream` group were unavailable or
  returning an error, then receiving an erroneous response from the
  last one might be considered a success despite the
  [proxy_next_upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-next-upstream) directive settings.
- If path in the [try_files](https://en.angie.software//angie/docs/configuration/modules/http/index.md#try-files) directive was shorter than a
  prefix in the relevant `location` block, then using a
  [proxy_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass) with a URI could crash a worker process; the fix was ported from
  nginx 1.29.4.
- If an ACME client was not referenced in a `stream` block via
  any `acme` directive, using any of the corresponding
  `$acme_cert_*` variables in that block would cause the configuration to be rejected
  with an `unknown variable` error; the bug had appeared in 1.10.3.
- If preserving of the cache index to a file was configured,
  the configuration test during operation might end with errors
  `[alert] mmap() failed (17: File exists)` and `[alert] munmap()
  failed (22: Invalid argument)`.
- The [proxy_method](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-method) directive was ignored if
  `proxy_cache_convert_head on` was triggered.
- The duration of the time-out specified by the `fail_timeout`
  option of the `server` directive within an `upstream` block was
  actually one second longer.
- Angie could not be built on `NetBSD 10.0`.
  Thanks to Maxim Dounin (freenginx).
- Loading modules built for Angie PRO could cause issues and
  crashes due to ABI incompatibility; now such incorrect configurations
  are prohibited with a relevant error message.



#### Packages

- Updated:
  - [angie-module-echo](https://en.angie.software//angie/docs/configuration/modules/external-modules/echo.md#external-echo), to version v0.64



### Angie 1.10.3

Release date: 13.11.2025.



#### Security

- Processing of a specially crafted login/password when using
  the `none` authentication method in the SMTP module might cause
  worker process memory disclosure to the authentication server
  ([CVE-2025-53859](https://nvd.nist.gov/vuln/detail/CVE-2025-53859)); the fix was ported from nginx 1.29.1.



#### Bugfixes

- When the `renew_on_load` option of the [acme_client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client)
  directive was used, a previously obtained certificate would not be
  loaded if it existed. This could limit functionality until the
  certificate renewal was completed. If the certificate did not exist,
  attempts to obtain a new one would fail with the error `[alert]
  lseek() failed (9: Bad file descriptor)`.
- If an [ACME client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#id1) was referenced in the `stream` block but
  not the `http` block, it was disabled with the warning `[warn] ACME
  client ... is defined but not used` and would never fetch a
  certificate.
- If all [acme_client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) directives had the `enabled=off`
  parameter and the relevant `$acme_cert_*` variables were used in the
  configuration, Angie would not start, reporting the error `[emerg]
  unknown acme_cert_* variable`.
- If the [ACME client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#id1) was used in the `stream` block that came
  before an `http` block, Angie would not start, reporting the error
  `[emerg] ACME client .. is not defined but referenced`.
- Some `client` block configurations might cause worker
  processes to crash when using variables that refer to an incoming
  connection missing in this case.



#### Packages

- Updated:
  - [angie-module-cache-purge](https://en.angie.software//angie/docs/configuration/modules/external-modules/cache-purge.md#external-cache-purge), to version 2.5.4
  - [angie-module-cgi](https://en.angie.software//angie/docs/configuration/modules/external-modules/cgi.md#external-cgi), to version v0.14.1
  - [angie-module-lua](https://en.angie.software//angie/docs/configuration/modules/external-modules/lua.md#external-lua), to version 0.10.29
  - [angie-module-njs](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs), to version 0.9.4

---



### Angie 1.10.2

Release date: 21.08.2025.



#### Bugfixes

- Proxy module settings in the `http` block could break
  functionality of modules that use the `client` block for outgoing
  requests; the bug had appeared in 1.10.0.
- Enabling [proxy_ignore_client_abort](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ignore-client-abort) together with modules
  that use the `client` block for outgoing requests could lead to
  worker process crashes; the bug had appeared in 1.10.0.
- If a single server was pre-configured in an upstream group,
  servers added via the [Docker API](https://en.angie.software//angie/docs/configuration/modules/http/http_docker.md#http-docker) might not be included in load
  balancing.
- If the only server in an upstream group was added via the
  [Docker API](https://en.angie.software//angie/docs/configuration/modules/http/http_docker.md#http-docker), it might be excluded from load balancing when detected to
  be unavailable.



#### Packages

- Dynamic modules added:
  - [angie-module-auth-totp](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-totp.md#external-auth-totp)
  - [angie-module-combined-upstreams](https://en.angie.software//angie/docs/configuration/modules/external-modules/combined-upstreams.md#external-combined-upstreams)
- Updated:
  - [angie-module-opentracing](https://en.angie.software//angie/docs/configuration/modules/external-modules/opentracing.md#external-opentracing), to version 0.41.0

---



### Angie 1.10.1

Release date: 17.07.2025.



#### Changes

- Directives specified in the `client` block can now only be inherited by
  explicitly declared `location` blocks within that block, so they don't
  affect the configuration of other modules that implicitly use the
  `client` block for outgoing requests.



#### Features

- Support for multiple `client` blocks allows common settings for
  different `location` blocks to be grouped within each block, which
  mitigates configuration duplication.



#### Bugfixes

- When the `reuseport` parameter was used in the `listen` directive,
  all connections to the specified address and port were handled by a single
  worker process; the bug had appeared in version 1.10.0.
- An HTTP/3 handshake with an upstream server might fail with OpenSSL library
  version 3.5.0 or later if the QUIC protocol `retry` mode was active on
  the server.
- Building the `HTTP/2` and `HTTP/3` modules using GCC 15 resulted
  in an error.
- Building with the `-O3` flag could result in an error when using GCC.

---



### Angie 1.10.0

Release date: 03.07.2025.



#### Features

- Automatic retrieval and dynamic updating of proxied server groups based on
  Docker (or Podman) container labels, configured using the
  [docker_endpoint](https://en.angie.software//angie/docs/configuration/modules/http/http_docker.md#docker-endpoint) directive. This enables real-time monitoring of
  container start and stop events via the specified Docker API endpoint, and
  allows their addresses to be added to or removed from an `upstream`
  group based on their labels — all without requiring a configuration reload.
- Support for automatic certificate acquisition in the `stream` module
  via the ACME protocol, configured with the [acme](https://en.angie.software//angie/docs/configuration/modules/stream/stream_acme.md#s-acme) directive and
  variables like [$acme_cert_\*](https://en.angie.software//angie/docs/configuration/modules/stream/stream_acme.md#v-s-acme-cert-name) and
  [$acme_cert_key_\*](https://en.angie.software//angie/docs/configuration/modules/stream/stream_acme.md#v-s-acme-cert-key-name).
- Support for handling MPTCP connections using the `multipath` parameter
  of the [listen](https://en.angie.software//angie/docs/configuration/modules/http/index.md#listen) directive.
  Thanks to Maxim Dounin (freenginx), Maxime Dourov, and Anthony Doeraene.
- New [client](https://en.angie.software//angie/docs/configuration/modules/http/index.md#client) block, which allows specification of additional
  configuration for internal HTTP requests issued by various modules.
- Includes all functionality from [nginx 1.27.5](https://nginx.org/en/CHANGES),
  including CUBIC congestion control for QUIC connections.



#### Packages

- Updated:
  - [angie-console-light](https://en.angie.software//angie/docs/installation/oss_packages.md#install-console-light-oss), to version 1.8.0
  - [angie-module-cgi](https://en.angie.software//angie/docs/configuration/modules/external-modules/cgi.md#external-cgi), to version 0.13
  - [angie-module-otel](https://en.angie.software//angie/docs/configuration/modules/external-modules/otel.md#external-otel), to version 0.1.2

14.07.2025

- Updated:
  - [angie-module-headers-more](https://en.angie.software//angie/docs/configuration/modules/external-modules/headers-more.md#external-headers-more), to version v0.39
  - [angie-module-njs](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs),
    [angie-module-njs-light](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs), to version 0.9.1

---



### Angie 1.9.1

Release date: 29.05.2025.



#### Features

- Support for IP addresses along with port numbers in the [acme_dns_port](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-dns-port)
  directive; both IPv4 and IPv6 are allowed.



#### Bugfixes

- Using both a wildcard domain and matching third-level domains in
  [server_name](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server-name) directives could cause the ACME server to fail when
  issuing a certificate for these domains under a single ACME client.
- In the `stream` module, after a successful connection to the proxied
  server during a passive check, its status in the statistics API was
  erroneously displayed as `unavailable` until the session ended.
- HTTP/3 requests might stall and time out; the fix was ported from nginx
  1.29.0.
- An early error while establishing an HTTP/3 connection to a proxied server
  could cause a worker process to crash.
- When proxying via the HTTP/3 protocol, the number of active connections
  in the statistics could be displayed incorrectly.



#### Packages

- Dynamic modules added:
  - [angie-module-njs-light](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs)
- Updated:
  - [angie-module-auth-spnego](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-spnego.md#external-auth-spnego), to version 1.1.3
  - [angie-module-cgi](https://en.angie.software//angie/docs/configuration/modules/external-modules/cgi.md#external-cgi), to version 0.12.1
  - [angie-module-modsecurity](https://en.angie.software//angie/docs/configuration/modules/external-modules/modsecurity.md#external-modsec), to version 1.0.4
  - [angie-module-njs](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs), to version 0.9.0
  - [angie-module-opentracing](https://en.angie.software//angie/docs/configuration/modules/external-modules/opentracing.md#external-opentracing), to version 0.40.0

---



### Angie 1.9.0

Release date: 11.04.2025.



#### Features

- The ability to specify a file in the [proxy_cache_path](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-path) directive, where
  the contents of the shared memory zone with the cache index will be saved
  between server startups; this eliminates the need to reload the cache after a
  restart and allows the server to come back online almost immediately.
- Support of TLS 1.3 Early Data (0-RTT) in the `stream` module using the
  [ssl_early_data](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#s-ssl-early-data) directive.
- New `busy` state for upstream peers in the statistics API, indicating
  that a peer has reached the limit configured by the `max_conns` option.
- The `uri=` parameter in the [acme_hook](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-hook) directive allows redefining
  the hook request URI and supports variables.
- The `renew_on_load` parameter of the [acme_client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) directive allows
  forcing certificate renewal on config load.
- Build time is now displayed via the `build_time` field of the
  `/status/angie` statistics API object and in the output of the
  `-V` command-line option.
- All functionality of [nginx 1.27.4](https://nginx.org/en/CHANGES), except
  for the `keepalive_min_timeout` directive (a similar feature has existed
  since version 1.8.0).



#### Changes

- The `enabled=off` parameter in the [acme_client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) directive now
  disables only certificate renewal for the given client while preserving all
  other functionality; the key and certificate (if available) can be accessed
  via the `$acme_cert_*` variables, while the use of `$acme_hook_*`
  variables and the `acme` directives doesn't cause errors.
- The `no valid domain name defined for ACME client` error is now issued
  only if no valid (i.e., ACME-compliant) domain name is found in the
  `server` block that references an ACME client using the `acme`
  directive.



#### Bugfixes

- If built with NTLS support, inheritance of the `proxy_ssl_certificate`
  and `proxy_ssl_certificate_key` directives with variables did not work
  properly.



#### Packages

- Updated:
  - [angie-module-cgi](https://en.angie.software//angie/docs/configuration/modules/external-modules/cgi.md#external-cgi), to version 0.11.1
  - [angie-module-njs](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs), to version 0.8.10

---



### Angie 1.8.3

Release date: 02.04.2025.



#### Bugfixes

- The [status_zone](https://en.angie.software//angie/docs/configuration/modules/http/index.md#status-zone) statistics in the HTTP module's [server](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server) block could be
  miscalculated if requests within the same connection belonged to different
  statistics zones, or if an error occurred during early request processing; the
  bug had appeared in 1.8.2.



#### Packages

- Updated:
  - [angie-console-light](https://en.angie.software//angie/docs/installation/oss_packages.md#install-console-light-oss), to version 1.7.0
  - [angie-module-cgi](https://en.angie.software//angie/docs/configuration/modules/external-modules/cgi.md#external-cgi), to version 57f660bb2c6ef6e4b75c65406080d0236860ca08
  - [angie-module-jwt](https://en.angie.software//angie/docs/configuration/modules/external-modules/jwt.md#external-jwt), to version v3.4.3
  - [angie-module-ndk](https://en.angie.software//angie/docs/configuration/modules/external-modules/ndk.md#external-ndk), to version v0.3.4
  - [angie-module-opentracing](https://en.angie.software//angie/docs/configuration/modules/external-modules/opentracing.md#external-opentracing), to version v0.39.0
  - [angie-module-vts](https://en.angie.software//angie/docs/configuration/modules/external-modules/vts.md#external-vts), to version v0.2.4

04.04.2025

- Updated:
  - [angie-console-light](https://en.angie.software//angie/docs/installation/oss_packages.md#install-console-light-oss), to version 1.7.1

07.04.2025

- Updated:
  - [angie-console-light](https://en.angie.software//angie/docs/installation/oss_packages.md#install-console-light-oss), to version 1.7.2



### Angie 1.8.2

Release date: 13.02.2025.



#### Security

- Insufficient validation while handling virtual servers with TLSv1.3 SNI
  allowed SSL sessions to be reused in a different virtual server,
  bypassing client SSL certificate verification ([CVE-2025-23419](https://www.cve.org/CVERecord?id=CVE-2025-23419));
  the fix was ported from nginx 1.27.4.



#### Bugfixes

- API requests to retrieve statistic values from an individual zone,
  which was set via variables,
  could cause a worker process to enter an infinite loop.
- HTTP/3 requests were not counted in zone statistics;
  the bug had appeared in 1.8.0.
- TLS handshakes using QUIC protocol were not counted in SSL statistics.
- Certificate renewal via the [ACME protocol](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#id1) could fail
  for server names prefixed with a dot in the [server_name](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server-name) directive.



#### Packages

- Dynamic modules added:
  - [angie-module-auth-pam](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-pam.md#external-auth-pam)
  - [angie-module-cgi](https://en.angie.software//angie/docs/configuration/modules/external-modules/cgi.md#external-cgi)

---

## 2024



### Angie 1.8.1

Release date: 28.12.2024.



#### Bugfixes

- Using the [status_zone](https://en.angie.software//angie/docs/configuration/modules/http/index.md#status-zone) directive in the `server` block of the
  HTTP module caused excessive logging of empty requests in [access_log](https://en.angie.software//angie/docs/configuration/modules/http/http_log.md#access-log) on
  TLS handshakes; the bug had appeared in 1.8.0.
- Decoding errors in HTTP/3 stream could cause a worker process crash when
  closing a QUIC connection; the fix was ported from nginx 1.27.4.
- Sending QUIC protocol version negotiation packets could cause an infinite
  packet exchange loop; the fix was ported from nginx 1.27.4.
- Using DNS-challenge without hooks in the [ACME](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme) module could
  cause a worker process crash in some configurations.



#### Packages

- Updated:
  - [angie-module-auth-jwt](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-jwt.md#external-auth-jwt), to version 0.9.0

23.01.2025

- Updated:
  - [angie-console-light](https://en.angie.software//angie/docs/installation/oss_packages.md#install-console-light-oss), to version 1.6.0

27.01.2025

- Dynamic modules added:
  - [angie-module-unbrotli](https://en.angie.software//angie/docs/configuration/modules/external-modules/unbrotli.md#external-unbrotli)
- Updated:
  - [angie-console-light](https://en.angie.software//angie/docs/installation/oss_packages.md#install-console-light-oss), to version 1.6.1
  - [angie-module-auth-spnego](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-spnego.md#external-auth-spnego), to version v1.1.2
  - [angie-module-headers-more](https://en.angie.software//angie/docs/configuration/modules/external-modules/headers-more.md#external-headers-more), to version v0.38
  - [angie-module-lua](https://en.angie.software//angie/docs/configuration/modules/external-modules/lua.md#external-lua), to version 0.10.28
  - [angie-module-njs](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs), to version 0.8.9
  - [angie-module-vts](https://en.angie.software//angie/docs/configuration/modules/external-modules/vts.md#external-vts), to version v0.2.3
  - [angie-module-wasm](https://en.angie.software//angie/docs/configuration/modules/wasm/index.md#wasm-core), to version v0.2-beta2

---



### Angie 1.8.0

Release date: 19.12.2024.



#### Features

- Support of `DNS-01` challenges by handling DNS queries from the ACME
  server, which allows to automatically request certificates of any types,
  including wildcard ones.
- Hooks system in the ACME module, configurable using the [acme_hook](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-hook)
  directive, which allows handling of domain name challenges using an external
  application to provide integration with various services and DNS hosting
  providers.
- The ACME module logs some additional information: why exactly the certificate
  is being renewed, full domain name list, client's account ID, long periods of
  inactivity (e.g. pollings), and the domain name being challenged; this
  information simplifies troubleshooting and allows to specify the CAA DNS
  record.
- The `account_key` parameter of the [acme_client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) directive, which
  allows to reuse an existing key for the ACME server account instead of
  auto-generating a new one.
- Support for variables in the [status_zone](https://en.angie.software//angie/docs/configuration/modules/http/index.md#status-zone) directives in the stream and
  HTTP modules allows to dynamically account statistics within several zones in
  a single `location` or `server` block; in particular, it's
  especially useful when a single `server` block is handling multiple
  virtual hosts.
- GZip HTTP compression module compatibility with the `zlib-ng` versions
  2.2.0 and above, which could previously cause `[alert] gzip filter
  failed to use preallocated memory` messages in the error log.
- The [max_headers](https://en.angie.software//angie/docs/configuration/modules/http/index.md#max-headers) directive that limits the number of HTTP request header
  fields to better protect against DoS attacks. Thanks to Maxim Dounin
  (freenginx) and Maksim Yevmenkin.
- The [http3_max_table_capacity](https://en.angie.software//angie/docs/configuration/modules/http/http_v3.md#http3-max-table-capacity) and [proxy_http3_max_table_capacity](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http3-max-table-capacity)
  directives to configure the HTTP/3 dynamic header compression table limits.
- Cross-compilation support - the build system can now use a wrapper script to
  run autotests, which enables to prepare a build without running test programs
  directly on the target platform.
- All functionality of [nginx 1.27.3](https://nginx.org/en/CHANGES).

#### Bugfixes

- HTTP/3 clients could time out when using `0-RTT`; the bug was inherited
  from nginx in version 1.7.0.
- Proxying with HTTP/3 using variables in the [proxy_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass) directive and
  without specifying an `upstream` block could crash the worker process.
- HTTP/3 upstreams using dynamic table could lead to worker process crash if
  used with cache.
- Some SSL handshakes could be not counted in statistics for the Stream module.
- HTTP/3 proxy settings specified in `http` or `server` level might
  be ignored.
- The [proxy_ssl_certificate](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ssl-certificate) directive didn't work when proxying via
  HTTP/3 with NTLS support enabled.



#### Changes

- When gracefully shutting down old worker processes, keep-alive connections are
  now closed only after the timeout specified by the [lingering_timeout](https://en.angie.software//angie/docs/configuration/modules/http/index.md#lingering-timeout)
  directive has expired; this behaviour allows to avoid possible client errors
  when receiving replies at that moment. Thanks to Maxim Dounin (freenginx).
- Disabled caching of the Stream module variables [$ssl_server_name](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-server-name),
  [$ssl_server_cert_type](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-server-cert-type), [$ssl_preread_protocol](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl_preread.md#v-ssl-preread-protocol), and
  [$ssl_preread_server_name](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl_preread.md#v-ssl-preread-server-name), which allows to get actual values when using
  virtual servers.

#### Packages

- Dynamic modules added:
  - [angie-module-http-auth-radius](https://en.angie.software//angie/docs/configuration/modules/external-modules/http-auth-radius.md#external-http-auth-radius)
- Updated:
  - [angie-module-auth-jwt](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-jwt.md#external-auth-jwt), to version 0.8.0
  - [angie-module-jwt](https://en.angie.software//angie/docs/configuration/modules/external-modules/jwt.md#external-jwt), to version 3.4.2
  - [angie-module-njs](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs), to version 0.8.8
  - [angie-module-opentracing](https://en.angie.software//angie/docs/configuration/modules/external-modules/opentracing.md#external-opentracing), to version 0.38.0
  - [angie-module-wasm](https://en.angie.software//angie/docs/configuration/modules/wasm/index.md#wasm-core), to version 0.1-beta5

---



### Angie 1.7.0

Release date: 19.09.2024.



#### Features

- Forced closing of all connections to a proxied server when it's removed from
  the group can be configured via the [proxy_connection_drop](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-connection-drop),
  [grpc_connection_drop](https://en.angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-connection-drop), [fastcgi_connection_drop](https://en.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-connection-drop),
  [scgi_connection_drop](https://en.angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-connection-drop), and [uwsgi_connection_drop](https://en.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-connection-drop) directives.
- Counters of sent DNS query types in the resolver statistics API, which is
  collected with the `status_zone` parameter of the [resolver](https://en.angie.software//angie/docs/configuration/modules/http/index.md#resolver)
  directive.
- The [$ssl_server_cert_type](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-server-cert-type) variable that contains the type of selected
  certificate for a received TLS connection.
- Disabling creation of the PID file with the `off` parameter of the
  [pid](https://en.angie.software//angie/docs/configuration/modules/core.md#pid) directive, which might be beneficial with immutable images and
  direct control by a service manager. Thanks to Maxim Dounin (freenginx).
- Creation of the PID file made atomic via an intermediate temporary file, which
  removes a moment when the file is already in the directory but still empty,
  and allows external programs to handle it more easily and reliably.
- Now, during reconfiguration, no attempt is made to recreate the PID file if
  the name in the [pid](https://en.angie.software//angie/docs/configuration/modules/core.md#pid) directive has changed but points to the same file
  via symlinks; in particular, it allows avoiding issues on systems that migrate
  from `/var/run/angie.pid` to `/run/angie.pid`. Thanks to Maxim
  Dounin (freenginx).
- [Syslog logging](https://en.angie.software//angie/docs/configuration/processing.md#syslog-logging) errors are now reported no more than
  once per second; this helps avoid flooding the logs with such messages when
  the syslog server is down or overloaded. Thanks to Maxim Dounin (freenginx).
- In the Mail proxy module, the maximum number of commands during
  authentication, configured with the [max_commands](https://en.angie.software//angie/docs/configuration/modules/mail/index.md#max-commands) directive, is limited
  to better protect against DoS attacks. Thanks to Maxim Dounin (freenginx).
- The [--feature-cache](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure) option of the
  **./configure** script to cache its results for optimization when
  building multiple modules or cross-compiling.
- All functionality of [nginx 1.27.1](https://nginx.org/en/CHANGES).

#### Bugfixes

- `PID file ... not readable (yet?) after start` and `Failed to
  parse PID from file...` errors might appear when starting with
  **systemd**. Thanks to Maxim Dounin (freenginx).



#### Changes

- Updated descriptions of HTTP status codes in conformance with RFC 9110. Thanks
  to Maxim Dounin (freenginx) and Michiel W. Beijen.
- A maximum of one empty line is now allowed before an HTTP request to better
  protect against DoS attacks. Thanks to Maxim Dounin (freenginx).
- HTTP/1.x header field names without a colon at the end are now prohibited;
  such invalid header fields from a client or a proxied server will now cause an
  error response. Thanks to Maxim Dounin (freenginx) and Maksim Yevmenkin.
- When reading a request body using HTTP/1.1 chunked transfer encoding, the
  total size of ignored chunk extensions and trailer header fields is now
  limited by the [client_max_body_size](https://en.angie.software//angie/docs/configuration/modules/http/index.md#client-max-body-size) directive to better protect against
  DoS attacks. Thanks to Maxim Dounin (freenginx) and Bartek Nowotarski.
- The MIME type in the `mime.types` configuration file has been changed to
  `image/bmp` for the `bmp` extension and
  `application/vnd.rar` for the `rar` extension; set to
  `application/vnd.debian.binary-package` for the `deb` and
  `udeb` extensions. Thanks to Yuriy Izorkin.

#### Packages

- Updated:
  - [angie-module-opentracing](https://en.angie.software//angie/docs/configuration/modules/external-modules/opentracing.md#external-opentracing), to version 0.36.0
  - [angie-module-lua](https://en.angie.software//angie/docs/configuration/modules/external-modules/lua.md#external-lua), to version 0.10.27

24.10.2024

- Added packages for [SberLinux](https://en.angie.software//angie/docs/installation/oss_packages.md#install-yum-oss).

29.11.2024

- Added WASM support with the following packages:
  - [angie-module-wamr](https://en.angie.software//angie/docs/configuration/modules/wasm/wasm_wamr.md#wasm-wamr)
  - [angie-module-wasm](https://en.angie.software//angie/docs/configuration/modules/wasm/index.md#wasm-core)
  - [angie-module-wasmtime](https://en.angie.software//angie/docs/configuration/modules/wasm/wasm_wasmtime.md#wasm-wasmtime)

---



### Angie 1.6.2

Release date: 16.08.2024.



#### Security

- Processing a specially crafted MP4 file with the
  [MP4](https://en.angie.software//angie/docs/configuration/modules/http/http_mp4.md#http-mp4)
  could cause a worker process crash
  ([CVE-2024-7347](https://nvd.nist.gov/vuln/detail/CVE-2024-7347));
  the fix was ported from nginx 1.27.1.

---



### Angie 1.6.1

Release date: 08.08.2024.



#### Features

- A new `passed` counter in the
  [API statistics](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-stream-server-zones)
  of the [Stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) module's [status_zone](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#s-status-zone) directive
  tracks connections passed to other sockets
  using [pass](https://en.angie.software//angie/docs/configuration/modules/stream/stream_pass.md#s-pass) directives.

#### Bugfixes

- When using virtual servers or the [pass](https://en.angie.software//angie/docs/configuration/modules/stream/stream_pass.md#s-pass) directives in the
  [Stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) module,
  connections could be accounted incorrectly in the statistics API.
- Worker processes could crash on configurations with 5 ACME
  clients or more; the bug had appeared in 1.6.0.
- Handling cached responses with the `X-Accel-Redirect` header
  could crash the worker process.
  Thanks to Maxim Dounin (freenginx) and Jiří Setnička.

#### Packages

- Updated:
  - [angie-console-light](https://en.angie.software//angie/docs/installation/oss_packages.md#install-console-light-oss), to version 1.4.0
  - [angie-module-opentracing](https://en.angie.software//angie/docs/configuration/modules/external-modules/opentracing.md#external-opentracing), to version 0.35.3
  - [angie-module-zstd](https://en.angie.software//angie/docs/configuration/modules/external-modules/zstd.md#external-zstd), to revision `f4ba115`

---



### Angie 1.6.0

Release date: 28.06.2024.



#### Features

- The [sticky](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-sticky) directive and related options
  in the [Stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) module's [upstream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-upstream) block,
  which allow to configure sticky sessions mode
  where all connections in the session are routed to the same server.
- Extraction of Cookie values from RDP connections using the
  [rdp_preread](https://en.angie.software//angie/docs/configuration/modules/stream/stream_rdp_preread.md#s-rdp-preread) directive in the [Stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) module
  into [$rdp_cookie](https://en.angie.software//angie/docs/configuration/modules/stream/stream_rdp_preread.md#v-rdp-cookie) and [$rdp_cookie_NAME](https://en.angie.software//angie/docs/configuration/modules/stream/stream_rdp_preread.md#id3) variables,
  which allows to log and stick RDP client sessions to particular servers
  while load balancing.
- Support for multiple [acme](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#id1) directives
  in a [server](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server) block,
  which allows to configure obtaining two types of certificates at once
  for that virtual server.
- Command line options `-m` and `-M`
  to list built-in and loaded modules.
- Support for [BoringSSL](https://www.chromium.org/Home/chromium-security/boringssl/)
  in the [ACME](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme) module.
- All functionality of [nginx 1.27.0](https://nginx.org/en/CHANGES),
  including support for virtual servers in the [Stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) module
  and the `pass` directive,
  which allows to pass accepted connections
  for handling to another listening sockets,
  including [HTTP](https://en.angie.software//angie/docs/configuration/modules/index.md#modules-http) and [Mail](https://en.angie.software//angie/docs/configuration/modules/index.md#modules-mail) modules.

#### Bugfixes

- Certificate request via the ACME protocol could result in
  error on some configurations with a log message like
  `[alert] getsockname() failed (9: Bad file descriptor)`.
- Certificate request with large number of domain names via the
  ACME protocol could result in error with a log message like
  `[error] JSON parser error`.
- ACME clients in configurations
  with multiple [error_log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log) directives
  could log messages to irrelevant logs.

#### Packages

- Updated:
  - [angie-module-auth-jwt](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-jwt.md#external-auth-jwt), to version 0.7.0
  - [angie-module-auth-ldap](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-ldap.md#external-ldap), to revision `241200e`
  - [angie-module-jwt](https://en.angie.software//angie/docs/configuration/modules/external-modules/jwt.md#external-jwt), to version 3.4.1
  - [angie-module-keyval](https://en.angie.software//angie/docs/configuration/modules/external-modules/keyval.md#external-keyval), to version 0.3.0
  - [angie-module-lua](https://en.angie.software//angie/docs/configuration/modules/external-modules/lua.md#external-lua):
    `stream_lua_module`, to revision `bea8a0c`
  - [angie-module-njs](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs), to version 0.8.5

---



### Angie 1.5.2

Release date: 03.06.2024.



#### Security

- When using HTTP/3, processing of a specially crafted QUIC
  session could cause a worker process crash, worker process memory
  disclosure on systems with MTU larger than 4096 bytes, or have other
  impact ([CVE-2024-32760](https://nvd.nist.gov/vuln/detail/CVE-2024-32760),
  [CVE-2024-31079](https://nvd.nist.gov/vuln/detail/CVE-2024-31079),
  [CVE-2024-35200](https://nvd.nist.gov/vuln/detail/CVE-2024-35200),
  [CVE-2024-34161](https://nvd.nist.gov/vuln/detail/CVE-2024-34161));
  the fix has been ported from nginx 1.26.1.

#### Packages

- Updated:
  - [angie-module-opentracing](https://en.angie.software//angie/docs/configuration/modules/external-modules/opentracing.md#external-opentracing), to version 0.35.2

---



### Angie 1.5.1

Release date: 16.05.2024.

#### Bugfixes

- The `proxy_next_upstream` mechanism did not work correctly when using
  the [resolve](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-reresolve) option of the `server`
  directive in the `upstream` block if
  the number of resolved IP addresses differed from the number of specified
  servers.
- While requesting a certificate via the ACME protocol, a
  segmentation fault could occur in a worker process.
- The [slow_start](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-slow-start) mechanism did not work when proxying TCP
  connections in the [Stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) module.
- HTTP/3 requests could result in an error if received as TLS
  1.3 early data; the bug had appeared in 1.4.0.
- HTTP/3 connection could be prematurely closed while using
  0-RTT in QUIC.
- When reading a request body from a fast connection, reading
  for a long time was possible. Thanks to Maxim Dounin (freenginx).



#### Changes

- Now ACME clients do not discard previously stored
  certificates that were expired or issued for a different domain list,
  but use them while renewing.

#### Packages

27.05.2024

- Added packages for [Alpine](https://en.angie.software//angie/docs/installation/oss_packages.md#install-alpine-oss) 3.20.

---



### Angie 1.5.0

Release date: 27.03.2024.

#### Features

- Basic support for automatically obtaining and updating certificates using the
  [ACME protocol](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme), configurable with the
  [acme_client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) and [acme](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#id1) directives, as well as variables of the
  form [$acme_cert_=](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-cert-name) and [$acme_cert_key_=](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-cert-key-name).
- Configuration of automatic redirection, which adds trailing
  slashes to request URIs, with the [auto_redirect](https://en.angie.software//angie/docs/configuration/modules/http/index.md#auto-redirect) directive.
- Output [statistics metrics](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#metrics) with dates in Epoch format
  instead of ISO 8601 for use in Prometheus and optionally in the JSON API
  with the `?date-epoch` request argument.
- New `recovering` state for upstream peers in the [statistics API](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#metrics), indicating that a peer is slowly starting up after a failure, as
  suggested by the `slow_start` option.
- Now the `-V` switch also shows the relevant version of nginx, which is
  useful for compatibility with third-party utilities, **certbot** in
  particular. Thanks to [AdvTechnoKing](https://github.com/webserver-llc/angie/commit/eb914d43aa6a2231d7321c808cb4180abb013ca0).
- All functionality of [nginx 1.25.4](https://nginx.org/en/CHANGES).

#### Bugfixes

- If the SSL session reuse mechanism ([proxy_ssl_session_reuse](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ssl-session-reuse)) was used and
  the list of proxied servers was dynamically updated, a leak could occur in the
  shared memory zone (`zone`) configured for the corresponding `upstream` block.

#### Packages

- Added packages for [FreeBSD 13](https://en.angie.software//angie/docs/installation/oss_packages.md#install-freebsd-oss) (arm64),
  [RED OS 8](https://en.angie.software//angie/docs/installation/oss_packages.md#install-yum-oss) (x86-64).
- Dynamic modules added:
  - [angie-module-otel](https://en.angie.software//angie/docs/configuration/modules/external-modules/otel.md#external-otel)
- Updated:
  - [angie-module-opentracing](https://en.angie.software//angie/docs/configuration/modules/external-modules/opentracing.md#external-opentracing), to version 0.34.0

28.03.2024

- Updated:
  - [angie-console-light](https://en.angie.software//angie/docs/installation/oss_packages.md#oss-packages), to version 1.3.0

16.04.2024

- Dynamic modules added:
  - [angie-module-zstd](https://en.angie.software//angie/docs/configuration/modules/external-modules/zstd.md#external-zstd)
- Updated:
  - [angie-module-njs](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs), to version 0.8.4

25.04.2024

- Dynamic modules added:
  - angie-module-vts: includes
    [module-vts](https://github.com/vozlt/nginx-module-vts),
    [module-sts](https://github.com/vozlt/nginx-module-sts),
    [module-stream-sts](https://github.com/vozlt/nginx-module-stream-sts)

---



### Angie 1.4.1

Release date: 15.02.2024.



#### Security

- When using HTTP/3, a segmentation error may have occurred in a worker process
  while processing a specially crafted QUIC session
  ([CVE-2024-24989](https://nvd.nist.gov/vuln/detail/CVE-2024-24989));
  note that Angie as of 1.4.0 is already not vulnerable to
  [CVE-2024-24990](https://nvd.nist.gov/vuln/detail/CVE-2024-24990).

#### Packages

- Dynamic modules added:
  - [angie-module-dynamic-limit-req](https://en.angie.software//angie/docs/configuration/modules/external-modules/dynamic-limit-req.md#external-dynamic-limit-req)
- Updated:
  - [angie-module-njs](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs), to version 0.8.3
  - [angie-module-vod](https://en.angie.software//angie/docs/configuration/modules/external-modules/vod.md#external-vod), to version 1.33

## 2023



### Angie 1.4.0

Release date: 12.12.2023.

#### Features

- Support for establishing HTTP/3 connections to upstream
  servers in the HTTP [Proxy](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy) module while allowing clients
  to use arbitrary HTTP versions. Configuration is done with the
  [proxy_http_version](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http-version) directive and a set of
  `proxy_quic_` and `proxy_http3_` directives.
- A mechanism for smoothly bringing the proxied server online
  after a failure using the `slow_start` option of the [server](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server)
  directive in the [upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) block.
- [mqtt_preread](https://en.angie.software//angie/docs/configuration/modules/stream/stream_mqtt_preread.md#s-mqtt-preread) directive in the [Stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) module, which
  allows extracting the username and client ID from the CONNECT packet
  of the MQTT protocol into the [$mqtt_preread_username](https://en.angie.software//angie/docs/configuration/modules/stream/stream_mqtt_preread.md#v-mqtt-preread-username)
  and [$mqtt_preread_clientid](https://en.angie.software//angie/docs/configuration/modules/stream/stream_mqtt_preread.md#v-mqtt-preread-clientid) variables.
- Limiting the response rate of MP4 files transmission to the
  client proportionally to the bitrate using the [mp4_limit_rate](https://en.angie.software//angie/docs/configuration/modules/http/http_mp4.md#mp4-limit-rate)
  and [mp4_limit_rate_after](https://en.angie.software//angie/docs/configuration/modules/http/http_mp4.md#mp4-limit-rate-after) directives,
  which reduces the bandwidth load.
- All functionality of [nginx 1.25.3](https://nginx.org/en/CHANGES).

#### Bugfixes

- If a proxied server was the only one in a group, it could be
  incorrectly reported as `unavailable` in the
  [metrics API](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#metrics)
  even after recovery.

#### Packages

- Added packages for [Alpine](https://en.angie.software//angie/docs/installation/oss_packages.md#install-alpine-oss) 3.19.
- Dynamic modules added:
  - [angie-module-auth-ldap](https://github.com/kvspb/nginx-auth-ldap)
- Updated:
  - [angie-module-auth-jwt](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-jwt.md#external-auth-jwt), to version 0.4.0
  - [angie-module-headers-more](https://en.angie.software//angie/docs/configuration/modules/external-modules/headers-more.md#external-headers-more), to version 0.36
  - [angie-module-ndk](https://en.angie.software//angie/docs/configuration/modules/external-modules/ndk.md#external-ndk), to version 0.3.3
  - [angie-module-opentracing](https://en.angie.software//angie/docs/configuration/modules/external-modules/opentracing.md#external-opentracing), to version 0.33.0

18.12.2023

- Updated:
  - [angie-console-light](https://en.angie.software//angie/docs/installation/oss_packages.md#oss-packages), to version 1.2.0

25.12.2023

- Updated:
  - [angie-console-light](https://en.angie.software//angie/docs/installation/oss_packages.md#oss-packages), to version 1.2.1

22.01.2024

- Dynamic modules added:
  - [angie-module-zip](https://en.angie.software//angie/docs/configuration/modules/external-modules/zip.md#external-zip)
- Updated:
  - [angie-module-auth-jwt](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-jwt.md#external-auth-jwt), to version 0.6.0
  - [angie-module-headers-more](https://en.angie.software//angie/docs/configuration/modules/external-modules/headers-more.md#external-headers-more), to version 0.37
  - [angie-module-lua](https://en.angie.software//angie/docs/configuration/modules/external-modules/lua.md#external-lua):
    `http_lua_module`, to version 0.10.26;
    `stream_lua_module`, to version 0.0.14

---



### Angie 1.3.2

Release date: 23.11.2023.

#### Bugfixes

- Possible incorrect values of metrics in [Prometheus](https://en.angie.software//angie/docs/configuration/modules/http/http_prometheus.md#id1) output
  that used variables other than `$p8s_value` for their values; in practice
  the issue could occur with `angie_http_upstreams_peers_state` and
  `angie_stream_upstreams_peers_state` from the standard
  `prometheus_all.conf` template.
- Some connection attempts to upstream servers might not have been properly
  accounted for in the [statistics API](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#a-api) if they failed immediately;
  the bug had appeared in 1.3.0.

#### Packages

04.12.2023

- Dynamic modules added:
  - [angie-module-modsecurity](https://github.com/owasp-modsecurity/ModSecurity-nginx)

07.12.2023

- Updated:
  - [angie-console-light](https://en.angie.software//angie/docs/installation/oss_packages.md#oss-packages), to version 1.1.1

---



### Angie 1.3.1

Release date: 18.10.2023.



#### Security

- Added extra limitations to HTTP/2 stream handling for better protection
  against the DoS attack known as "HTTP/2 Rapid Reset" ([CVE-2023-44487](https://nvd.nist.gov/vuln/detail/CVE-2023-44487)).

#### Packages

26.10.2023

- Dynamic modules added:
  - [angie-module-opentracing](https://en.angie.software//angie/docs/configuration/modules/external-modules/opentracing.md#external-opentracing)

13.11.2023

- Dynamic modules added:
  - [angie-module-testcookie](https://en.angie.software//angie/docs/configuration/modules/external-modules/testcookie.md#external-testcookie)
- Updated:
  - [angie-console-light](https://en.angie.software//angie/docs/installation/oss_packages.md#oss-packages), to version 1.1.0
  - [angie-module-headers-more](https://en.angie.software//angie/docs/configuration/modules/external-modules/headers-more.md#external-headers-more), to version 0.35
  - [angie-module-njs](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs), to version 0.8.2
  - [angie-module-vod](https://en.angie.software//angie/docs/configuration/modules/external-modules/vod.md#external-vod), to version 1.32

---



### Angie 1.3.0

Release date: 19.09.2023.

#### Features

- Ability to specify multiple match patterns in the `location` directive,
  which allows to [combine](https://en.angie.software//angie/docs/configuration/modules/http/index.md#combined-locations) several `location`
  blocks with similar settings and therefore simplify configuration by reducing
  duplication.
- Export of varied statistics metrics in Prometheus format with flexible
  template configuration using the new [prometheus](https://en.angie.software//angie/docs/configuration/modules/http/http_prometheus.md#id1) and
  [prometheus_template](https://en.angie.software//angie/docs/configuration/modules/http/http_prometheus.md#prometheus-template) directives.
- Detailed information and [metrics](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-stream-upstreams) for
  groups of stream upstream servers in the statistics interface provided by the
  [api](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#a-api) directive.
- The [resolve](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-reresolve) option of the `server` directive in the
  Stream [Upstream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#stream-upstream) module's `upstream` block that
  allows to monitor changes to the list of IP addresses corresponding to a
  domain name, and automatically update it without the need of reloading
  configuration.
- The [service](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-reresolve) option of the `server` directive in the
  Stream [Upstream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#stream-upstream) module's `upstream` block that
  allows to retrieve lists of addresses from DNS SRV records, with basic
  priority support.
- Access to the contents of configuration files used by the current generation
  of worker processes via the interface provided by the [api](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#a-api) directive
  with the [api_config_files](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#a-api-config-files) directive enabled.
- Display of the [configuration generation](https://en.angie.software//angie/docs/configuration/runtime.md#control-config-change)
  number in process titles, which allows to monitor the success of
  configuration reloads and the number of previous worker process generations
  using the `ps` utility.
- All functionality of [nginx 1.25.2](https://nginx.org/en/CHANGES).



#### Bugfix

- Compilation failed when `./configure` options
  `--without-http_upstream_zone_module` or
  `--without-stream_upstream_zone_module` were used; the bug had appeared in 1.2.0.



#### Changes

- Now appname `angie` is used
  when loading the OpenSSL configuration.

#### Packages

- Updated:
  - [angie-module-njs](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs), to version 0.8.1

---



### Angie 1.2.0

Release date: 30.05.2023.

#### Features

- The [sticky](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky) directive and related options in the HTTP
  [Upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream) module's [upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) block that allow
  configuring sticky sessions mode, where all requests within a session are
  routed to the same server.
- The [$upstream_sticky_status](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-sticky-status) variable that takes either `NEW`,
  `HIT`, or `MISS` values depending on the success of routing the request to the
  relevant upstream server with sticky sessions enabled.
- Support for NTLS in the HTTP [SSL](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#http-ssl) and Stream
  [SSL](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#stream-ssl) modules when using the [TongSuo](https://github.com/Tongsuo-Project/Tongsuo) TLS library; the support can
  be enabled via the `‑‑with‑ntls` build time option and configured
  with the corresponding [ssl_ntls](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-ntls) and [proxy_ssl_ntls](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ssl-ntls) directives.
- In the HTTP [Proxy](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy) and Stream [Proxy](https://en.angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#stream-proxy)
  modules, the ability to specify multiple certificates with different types
  (RSA and ECDSA) and corresponding keys using the [proxy_ssl_certificate](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ssl-certificate)
  and [proxy_ssl_certificate_key](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ssl-certificate-key) directives.
- Display of version and build name in the `master` process title, which
  allows getting this information about a running server instance using the
  `ps` utility.
- The [GZip](https://en.angie.software//angie/docs/configuration/modules/http/http_gzip.md#http-gzip) module's ability to compress "207 Multi-Status"
  responses.  Thanks to [DBotThePony](https://github.com/webserver-llc/angie/pull/26).
- All functionality of [nginx 1.25.0](https://nginx.org/en/CHANGES),
  including [HTTP/3](https://en.angie.software//angie/docs/configuration/modules/http/http_v3.md#http-v3) support.

#### Packages

- Added packages for [Ubuntu 23.04 "Lunar Lobster"](https://en.angie.software//angie/docs/installation/oss_packages.md#install-deb-oss).
- Dynamic modules added:
  - `angie-module-lua` package includes
    [http_lua_module](https://github.com/openresty/lua-nginx-module)
    and
    [stream_lua_module](https://github.com/openresty/stream-lua-nginx-module).
  - [angie-module-redis2](https://en.angie.software//angie/docs/configuration/modules/external-modules/redis2.md#external-redis2)

13.06.2023

- Added packages for [Debian 12 "Bookworm"](https://en.angie.software//angie/docs/installation/oss_packages.md#install-deb-oss) and
  [AlmaLinux](https://en.angie.software//angie/docs/installation/oss_packages.md#install-yum-oss).

12.07.2023

- Dynamic modules added:
  - [angie-module-cache-purge](https://en.angie.software//angie/docs/configuration/modules/external-modules/cache-purge.md#external-cache-purge)
  - [angie-module-echo](https://en.angie.software//angie/docs/configuration/modules/external-modules/echo.md#external-echo)
  - [angie-module-keyval](https://en.angie.software//angie/docs/configuration/modules/external-modules/keyval.md#external-keyval)
  - [angie-module-postgres](https://en.angie.software//angie/docs/configuration/modules/external-modules/postgres.md#external-postgres)
- Updated:
  - [angie-module-njs](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs), to version 0.8.0.

28.07.2023

- Dynamic modules added:
  - [angie-module-auth-jwt](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-jwt.md#external-auth-jwt)

18.08.2023

- Dynamic modules added:
  - [angie-module-enhanced-memcached](https://en.angie.software//angie/docs/configuration/modules/external-modules/enhanced-memcached.md#external-enhanced-memcached)
  - [angie-module-eval](https://en.angie.software//angie/docs/configuration/modules/external-modules/eval.md#external-eval)

---



### Angie 1.1.0

Release date: 24.01.2023.

#### Features

- The [resolve](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve) option of the [server](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) directive in the
  HTTP [Upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream) module's [upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) block that
  allows monitoring changes to the list of IP addresses corresponding to a
  domain name, and automatically updating it without the need to reload
  configuration.
- The [service](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve) option of the [server](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) directive in the
  HTTP [Upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream) module's [upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) block that
  allows retrieving lists of addresses from DNS SRV records, with basic
  priority support.
- [Detailed information and metrics](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#a-upstream) for the groups of HTTP
  upstream servers in the statistics interface provided by the [api](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#a-api)
  directive.
- [autoindex](https://en.angie.software//angie/docs/configuration/modules/http/http_autoindex.md#id1) uses natural sorting order for directory listings.
- All functionality of [nginx 1.23.3](https://nginx.org/en/CHANGES).



#### Bugfix

- Compilation failed due to a false warning when using GCC 9 or older with the
  -O2 or higher optimization.

#### Packages

15.03.2023

- Added packages for [Oracle](https://en.angie.software//angie/docs/installation/oss_packages.md#install-yum-oss) and
  [Rocky](https://en.angie.software//angie/docs/installation/oss_packages.md#install-yum-oss) Linux.
- Dynamic modules added:
  - [angie-module-auth-spnego](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-spnego.md#external-auth-spnego)
  - [angie-module-brotli](https://en.angie.software//angie/docs/configuration/modules/external-modules/brotli.md#external-brotli)
  - [angie-module-dav-ext](https://en.angie.software//angie/docs/configuration/modules/external-modules/dav-ext.md#external-dav-ext)
  - [angie-module-headers-more](https://en.angie.software//angie/docs/configuration/modules/external-modules/headers-more.md#external-headers-more)
  - [angie-module-ndk](https://en.angie.software//angie/docs/configuration/modules/external-modules/ndk.md#external-ndk)
  - [angie-module-rtmp](https://en.angie.software//angie/docs/configuration/modules/external-modules/rtmp.md#external-rtmp)
  - [angie-module-set-misc](https://en.angie.software//angie/docs/configuration/modules/external-modules/set-misc.md#external-set-misc)

07.04.2023

- Added packages for [ALT](https://en.angie.software//angie/docs/installation/oss_packages.md#install-alt-oss) Linux.

11.05.2023

- Added packages for [FreeBSD](https://en.angie.software//angie/docs/installation/oss_packages.md#install-freebsd-oss).
- Dynamic modules added:
  - [angie-module-jwt](https://en.angie.software//angie/docs/configuration/modules/external-modules/jwt.md#external-jwt)
  - [angie-module-subs](https://en.angie.software//angie/docs/configuration/modules/external-modules/subs.md#external-subs)
  - [angie-module-upload](https://en.angie.software//angie/docs/configuration/modules/external-modules/upload.md#external-upload)
  - [angie-module-vod](https://en.angie.software//angie/docs/configuration/modules/external-modules/vod.md#external-vod)

26.05.2023

- Added packages for [Astra](https://en.angie.software//angie/docs/installation/oss_packages.md#install-astrase-oss) Linux Special Edition.

---

## 2022



### Angie 1.0.0

Release date: 27.10.2022.

#### Features

- The [api](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#a-api) directive that provides an HTTP RESTful interface for accessing
  in JSON format basic information about a web server instance, as well as
  [metrics](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#metrics) of client connections, shared memory zones, DNS
  queries, HTTP requests, HTTP responses cache, TCP/UDP sessions of the
  [Stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) module, and zones of the
  [Limit Conn](https://en.angie.software//angie/docs/configuration/modules/http/http_limit_conn.md#http-limit-conn)/[Limit Req](https://en.angie.software//angie/docs/configuration/modules/http/http_limit_req.md#http-limit-req) modules.
- The [status_zone](https://en.angie.software//angie/docs/configuration/modules/http/index.md#status-zone) directive in the [HTTP](https://en.angie.software//angie/docs/configuration/modules/http/index.md#http-core)
  module for specifying a zone to collect request metrics in [server](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server) and
  [location](https://en.angie.software//angie/docs/configuration/modules/http/index.md#location) contexts.
- The [status_zone](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#s-status-zone) directive in the [Stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) module for specifying a zone to collect TCP/UDP session metrics.
- The [status_zone](https://en.angie.software//angie/docs/configuration/modules/http/index.md#resolver-status) parameter of the [resolver](https://en.angie.software//angie/docs/configuration/modules/http/index.md#resolver)
  directive for specifying a zone to collect metrics on DNS queries.
- The [$angie_version](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-angie-version) variable with the version of Angie.
- All functionality of [nginx 1.23.2](https://nginx.org/en/CHANGES).


# https://en.angie.software/angie/docs/pro_changes.md





# Angie PRO Version History

## 2026



### Angie PRO 1.12.1

Release date: 17.07.2026.



#### Security

- When evaluating a string expression in which unnamed capture variables
  (`$1`, `$2`, etc.) preceded a [map](https://en.angie.software//angie/docs/configuration/modules/http/http_map.md#id1) directive
  variable whose value is determined by a regular expression, or when using a
  non-cacheable (`volatile`) [map](https://en.angie.software//angie/docs/configuration/modules/http/http_map.md#id1) directive variable whose
  key contained a capture variable also used in the value of the same
  directive, worker process memory corruption or a worker process crash could
  occur ([CVE-2026-42533](https://nvd.nist.gov/vuln/detail/CVE-2026-42533)); the fix was ported from
  nginx 1.31.3.
- When using the [slice](https://en.angie.software//angie/docs/configuration/modules/http/http_slice.md#id1) directive or
  [background cache update](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-background-update), if unnamed
  capture variables (`$1`, `$2`, etc.) were used together with a
  non-cacheable (`volatile`) [map](https://en.angie.software//angie/docs/configuration/modules/http/http_map.md#id1) directive variable with a
  regular expression, the value of an unnamed capture variable could contain
  arbitrary bytes from worker process memory, or a worker process crash could
  occur ([CVE-2026-60005](https://nvd.nist.gov/vuln/detail/CVE-2026-60005)); the fix was ported from
  nginx 1.31.3.
- When using the [SSI](https://en.angie.software//angie/docs/configuration/modules/http/http_ssi.md#http-ssi) module with unbuffered proxying, worker
  process memory corruption or a worker process crash could occur
  ([CVE-2026-56434](https://nvd.nist.gov/vuln/detail/CVE-2026-56434)); the
  fix was ported from nginx 1.31.3.



#### Bugfixes

- In certain cases when using the [Metric](https://en.angie.software//angie/docs/configuration/modules/http/http_metric.md#http-metric) module, metric
  data corruption could occur; in `expire=on` mode, this could also
  cause a worker process crash.



#### Packages

- Updated:
  - [angie-pro-module-auth-jwt](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-jwt.md#external-auth-jwt), to version 0.14.2



### Angie PRO 1.12.0

Release date: 13.07.2026.



#### Features

- The [Metric](https://en.angie.software//angie/docs/configuration/modules/stream/stream_metric.md#stream-metric) module for stream enabling arbitrarily
  configurable statistics collection; allows aggregating any
  connection-processing data at any stage in real time using variables grouped
  by custom keys, with various methods (counters, histograms, moving averages,
  etc.), and exposes them via the `/status/stream/metric_zones/`
  statistics API section (with Prometheus support).
- For the [feedback](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-feedback) load balancing method, a
  `feedback` field is now included in the statistics API for each proxied
  server, containing the current accumulated value of the dynamic weight used
  for load balancing.
- Information about certificates defined in the configuration, as well as those
  obtained by ACME clients, in the [/certificates/](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#certificates)
  statistics API section; allows easy monitoring of certificates loaded in the
  configuration.
- Obtaining certificates for IP addresses using ACME.
- Support for ACME profiles using the new `profile` parameter of the
  [acme_client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) directive; used in particular for requesting
  certificates for IP addresses in Let's Encrypt.
- Support for External Account Binding (EAB), which allows linking an ACME
  account with an external account at the certificate authority using HMAC
  authentication; required by some commercial certificate authorities.
- Enhanced compatibility with servers that do not strictly comply with the ACME
  protocol, particularly SSL.com.
- The [acme_dns_ttl](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-dns-ttl) directive that allows changing the TTL
  value in DNS query responses during domain verification for ACME; some
  providers filter DNS responses with a low TTL.
- Automatic retrieval of DNS server addresses from a file in
  `resolv.conf` format using the `conf` parameter of the
  [resolver](https://en.angie.software//angie/docs/configuration/modules/http/index.md#resolver) directive; the file is re-read when it changes,
  which simplifies configuration and eliminates the need to manually specify
  server addresses in the configuration.
- New [DoH](https://en.angie.software//angie/docs/configuration/modules/http/http_doh.md#http-doh) HTTP module implementing a DNS over HTTPS server
  (RFC 8484) that accepts DNS queries over HTTP/HTTPS and proxies them to DNS
  server groups via UDP or TCP.
- In the stream module, the [proxy_pass](https://en.angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-pass) directive now
  supports specifying a port for a named upstream group whose servers have no
  port defined; this allows a single upstream group to be used for proxying to
  different ports without duplicating the server list; a new
  [no_port](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-no-port) directive is added to explicitly mark an upstream
  group as portless.
- The [proxy_bind](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-bind) directive in HTTP and stream modules now
  evaluates variables after a proxied server is selected; allows the outgoing
  connection to be bound to an address relevant to the selected server.
- The new `$upstream_current_addr` variable in HTTP and stream modules,
  containing the address of the proxied server selected for the current
  connection attempt; unlike `$upstream_addr`, it always holds a single
  address and is available during server selection.
- Atomic dynamic switching of a proxied server between the primary and backup
  groups with a single request to change the value of the `backup` field
  in the [/config](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-config) API subsection.
- The Docker network in which container IP addresses are looked up can now be
  specified via an individual [Docker](https://en.angie.software//angie/docs/configuration/modules/http/http_docker.md#http-docker) label for each
  specific upstream group.
- The [goto](https://en.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#goto) directive in the rewrite module performs an internal
  redirect to a named location without modifying the URI; supports conditional
  execution inside an `if` block; replaces common workarounds based on
  `try_files` with a guaranteed-nonexistent path or `error_page`
  with `return` and an otherwise-unused status code.
- Log message filtering using the `filter=` parameter of the
  [error_log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log) directive, and the new
  [error_log_user_tag](https://en.angie.software//angie/docs/configuration/modules/http/index.md#error-log-user-tag) directive for adding tags that
  can then be used in filter conditions; allows flexible log configuration for
  tracking unique events on the server with the ability to attach various
  handlers to them.
- The `format=` parameter of the [error_log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log) directive,
  which allows switching the log message format to JSON.
- Limiting the maximum error logging rate using the `rate` parameter of
  the [error_log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log) directive; the default limit is 1000
  messages per second.
  Thanks to Maxim Dounin (freenginx).
- The [time_format](https://en.angie.software//angie/docs/configuration/modules/http/index.md#time-format) directive allows defining a variable
  with a custom time format, supporting strftime()-like specifiers as well as
  `%L` for milliseconds.
- Reduced CPU usage when using the [status_zone](https://en.angie.software//angie/docs/configuration/modules/http/index.md#status-zone) directive
  with variables in the HTTP and stream modules under high load.
- Built-in HTML error pages and the directory listing page of the
  [AutoIndex](https://en.angie.software//angie/docs/configuration/modules/http/http_autoindex.md#http-autoindex) module now support a dark color scheme
  following the user's OS-level preference.
- The new `$upstream_transport` variable exposes the transport protocol
  (TCP or UDP) used for each upstream connection attempt; values for multiple
  attempts are separated by a comma.
- The [ssl_keylog_file](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-keylog-file) and
  [proxy_ssl_keylog_file](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ssl-keylog-file) directives specify the
  file to log SSL session keys.
- All functionality of nginx 1.31.2, including the new
  [Tunnel](https://en.angie.software//angie/docs/configuration/modules/http/http_tunnel.md#http-tunnel) HTTP module for CONNECT tunneling and HTTP/2
  support for connections to proxied servers; the
  [keepalive](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive) directive in the `upstream` block is
  left disabled, as its use may lead to unexpected consequences in some
  scenarios that are not addressed by the proposed `local` option.



#### Changes

- In the HTTP and stream modules, the `resolver conf` directive is now
  set by default, using DNS servers from `/etc/resolv.conf`; to
  explicitly disable DNS resolution, as was previously the case when no
  [resolver](https://en.angie.software//angie/docs/configuration/modules/http/index.md#resolver) directive was present in the configuration, the
  new `off` parameter can be used.



#### Bugfixes

- If `$metric_*` or `$metric_*_key` variables were set
  sequentially for multiple metric zones within a single request, updating
  statistics or retrieving related variables used the key of the last specified
  zone.
- The `$metric_*` variable returned the specified string, not the key
  along with the calculated metric value. The `$metric_*_value` variable
  had to be used in order to get the actual value.
- A key used for statistics calculation in the [Metric](https://en.angie.software//angie/docs/configuration/modules/http/http_metric.md#http-metric)
  module could be truncated if it was specified together with a value and
  contained the `=` character.
- The [proxy_no_cache](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-no-cache) directive was not checked when
  caching errors.
  Thanks to Maxim Dounin (freenginx).
- Using the [add_header](https://en.angie.software//angie/docs/configuration/modules/http/http_headers.md#add-header) directive for `Content-Type`
  might result in the addition of another `Content-Type` field in the
  response header.
- The [least_time](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-least-time) load balancing in `header` and
  `first_byte` modes fell back to round-robin when no `zone`
  directive was present in the `upstream` block.
- The [ACME](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme) module was not functional with `select`
  and `poll` event processing methods.



#### Packages

- Updated:
  - [angie-pro-module-lua](https://en.angie.software//angie/docs/configuration/modules/external-modules/lua.md#external-lua), to version 0.10.31 / v0.0.17
  - [angie-pro-module-njs](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs), to version 1.0.0
  - [angie-pro-module-opentracing](https://en.angie.software//angie/docs/configuration/modules/external-modules/opentracing.md#external-opentracing), to version 0.48.0
  - [angie-pro-module-vod](https://en.angie.software//angie/docs/configuration/modules/external-modules/vod.md#external-vod), to version 1.9.0



### Angie PRO 1.11.8

Release date: 18.06.2026.



#### Security

- When proxying a specially crafted request to a gRPC backend with the
  [ignore_invalid_headers](https://en.angie.software//angie/docs/configuration/modules/http/index.md#ignore-invalid-headers) directive set to `off` and the
  [large_client_header_buffers](https://en.angie.software//angie/docs/configuration/modules/http/index.md#large-client-header-buffers) directive with a large value, a buffer
  overflow could occur, allowing an attacker to corrupt the worker process
  memory or cause its crash
  ([CVE-2026-42055](https://nvd.nist.gov/vuln/detail/CVE-2026-42055));
  the fix was ported from nginx 1.31.2.
- When processing a specially crafted response with UTF-8 decoding via the
  [charset_map](https://en.angie.software//angie/docs/configuration/modules/http/http_charset.md#charset-map) directive, an out-of-bounds read could occur, allowing an
  attacker to send limited worker process memory contents to the client or
  cause its crash
  ([CVE-2026-48142](https://nvd.nist.gov/vuln/detail/CVE-2026-48142));
  the fix was ported from nginx 1.31.2.



#### Bugfixes

- An IP address without a port number in the [acme_http_port](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-http-port) or
  [acme_dns_port](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-dns-port) directives caused a master process crash when reading
  the configuration.



#### Packages

- Updated:
  - [angie-pro-module-keyval](https://en.angie.software//angie/docs/configuration/modules/external-modules/keyval.md#external-keyval), to version 0.5.0



### Angie PRO 1.11.7

Release date: 15.06.2026.



#### Features

- Compatibility with OpenSSL 4.0.



#### Bugfixes

- In some configurations, the response to an ACME DNS challenge could be
  sent from a different IP address/interface than the one the request was
  received on, which could result in a certificate issuance failure.
- When using the [Docker](https://en.angie.software//angie/docs/configuration/modules/http/http_docker.md#http-docker) module, rapid termination of
  containers immediately after start could cause a worker process crash.
- Changing parameters in the [metric_zone](https://en.angie.software//angie/docs/configuration/modules/http/http_metric.md#metric-zone) or
  [metric_complex_zone](https://en.angie.software//angie/docs/configuration/modules/http/http_metric.md#metric-complex-zone) directives for an already
  existing zone could cause a worker process crash on configuration reload.
- When using the `window=` parameter of the `average mean`
  metric, the result could be calculated incorrectly on some intervals; in
  particular, shortly after system startup on Linux, the values could remain
  zero.
- The values of `count` and `histogram` metrics were output
  incorrectly on 32-bit platforms after reaching 2^32-1.



#### Packages

- Updated:
  - [angie-pro-module-auth-jwt](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-jwt.md#external-auth-jwt), to version 0.14.1
  - [angie-pro-module-opentracing](https://en.angie.software//angie/docs/configuration/modules/external-modules/opentracing.md#external-opentracing), to version v0.47.0
  - [angie-pro-module-vod](https://en.angie.software//angie/docs/configuration/modules/external-modules/vod.md#external-vod), to version v1.8.1



### Angie PRO 1.11.6

Release date: 25.05.2026.



#### Security

- When using the [rewrite](https://en.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#id5) directive with a regex containing nested
  PCRE captures and a replacement string referencing multiple such
  captures, an attacker, given conditions beyond the attacker's control,
  could cause a worker process crash, or, on systems without address
  space layout randomization, arbitrary code execution
  ([CVE-2026-9256](https://nvd.nist.gov/vuln/detail/CVE-2026-9256));
  the fix was ported from nginx 1.31.1.



#### Packages

- Updated:
  - [angie-pro-module-auth-jwt](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-jwt.md#external-auth-jwt), to version 0.13.1
  - [angie-pro-module-njs](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs), to version 0.9.9
  - [angie-pro-module-testcookie](https://en.angie.software//angie/docs/configuration/modules/external-modules/testcookie.md#external-testcookie), to version 7d263d4
  - [angie-pro-module-vod](https://en.angie.software//angie/docs/configuration/modules/external-modules/vod.md#external-vod), to version v1.7.2



### Angie PRO 1.11.5

Release date: 15.05.2026.



#### Security

- When the [rewrite](https://en.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#id5) directive with an unnamed capture (e.g.,
  `$1`, `$2`) and a replacement string containing `?` was followed by a
  [rewrite](https://en.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#id5), [if](https://en.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#if), or [set](https://en.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#set) directive, an attacker, given conditions
  beyond the attacker's control, could cause a worker process crash
  and, on systems without address space layout randomization, arbitrary
  code execution
  ([CVE-2026-42945](https://nvd.nist.gov/vuln/detail/CVE-2026-42945));
  the fix was ported from nginx 1.31.0.
- When using the [ssl_ocsp](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-ocsp) directive, a use of previously
  freed memory could occur while processing DNS server responses,
  allowing an attacker to corrupt the worker process memory or cause
  its crash
  ([CVE-2026-40701](https://nvd.nist.gov/vuln/detail/CVE-2026-40701));
  the fix was ported from nginx 1.31.0.
- When using HTTP/3, an attacker could spoof the IP address
  and thereby bypass restrictions or authorization in some
  configurations
  ([CVE-2026-40460](https://nvd.nist.gov/vuln/detail/CVE-2026-40460));
  the fix was ported from nginx 1.31.0.
- When [scgi_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-pass) or [uwsgi_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-pass) was configured, an
  attacker in a man-in-the-middle (MITM) position, controlling
  responses from a proxied server, could cause excessive memory
  allocation or an over-read of data, leading to the disclosure of
  worker process memory to the client or a process crash
  ([CVE-2026-42946](https://nvd.nist.gov/vuln/detail/CVE-2026-42946));
  the fix was ported from nginx 1.31.0.
- When processing a specially crafted response with UTF-8
  decoding via the [charset_map](https://en.angie.software//angie/docs/configuration/modules/http/http_charset.md#charset-map) directive, an out-of-bounds read could
  occur in the worker process, allowing an attacker, given conditions
  beyond the attacker's control, to send limited worker process memory
  contents to the client or cause process crash
  ([CVE-2026-42934](https://nvd.nist.gov/vuln/detail/CVE-2026-42934));
  the fix was ported from nginx 1.31.0.



#### Packages

- Updated:
  - [angie-pro-module-auth-totp](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-totp.md#external-auth-totp), to version 1.2.0
  - [angie-pro-module-cache-purge](https://en.angie.software//angie/docs/configuration/modules/external-modules/cache-purge.md#external-cache-purge), to version 3.0.2
  - [angie-pro-module-keyval](https://en.angie.software//angie/docs/configuration/modules/external-modules/keyval.md#external-keyval), to version 0.4.0
  - [angie-pro-module-njs](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs), to version 0.9.8
  - [angie-pro-module-opentracing](https://en.angie.software//angie/docs/configuration/modules/external-modules/opentracing.md#external-opentracing), to version v0.46.0
- Switched source of [angie-pro-module-dav-ext](https://en.angie.software//angie/docs/configuration/modules/external-modules/dav-ext.md#external-dav-ext) to
  [mid1221213/nginx-dav-ext-module](https://github.com/mid1221213/nginx-dav-ext-module) v4.0.1.
- Switched source of [angie-pro-module-vod](https://en.angie.software//angie/docs/configuration/modules/external-modules/vod.md#external-vod) to
  [dio-az/nginx-vod-module](https://github.com/dio-az/nginx-vod-module) v1.7.1.



### Angie PRO 1.11.4

Release date: 25.03.2026.



#### Security

- TLS handshake with a client in the [Stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) module might
  succeed despite OCSP rejecting the client certificate
  ([CVE-2026-28755](https://nvd.nist.gov/vuln/detail/CVE-2026-28755));
  the fix was ported from nginx 1.29.7.
- A buffer overflow might occur in the DAV module while
  handling a COPY or MOVE request in a `location` with the [alias](https://en.angie.software//angie/docs/configuration/modules/http/index.md#alias)
  directive, allowing an attacker to modify the source or destination
  path outside of the document root directory
  ([CVE-2026-27654](https://nvd.nist.gov/vuln/detail/CVE-2026-27654));
  the fix was ported from nginx 1.29.7.
- Processing of a specially crafted file by the MP4 module on
  32-bit platforms might cause a worker process crash, or might have
  potential other impact
  ([CVE-2026-27784](https://nvd.nist.gov/vuln/detail/CVE-2026-27784));
  the fix was ported from nginx 1.29.7.
- Processing of a specially crafted file by the MP4 module
  might cause a worker process crash, or might have potential other
  impact
  ([CVE-2026-32647](https://nvd.nist.gov/vuln/detail/CVE-2026-32647));
  the fix was ported from nginx 1.29.7.
- If the CRAM-MD5 or APOP authentication methods were used in
  the [Mail](https://en.angie.software//angie/docs/configuration/modules/mail/index.md#mail-core) proxy module and authentication retry was enabled,
  then a worker process could crash
  ([CVE-2026-27651](https://nvd.nist.gov/vuln/detail/CVE-2026-27651));
  the fix was ported from nginx 1.29.7.
- When the [Mail](https://en.angie.software//angie/docs/configuration/modules/mail/index.md#mail-core) proxy module was used, an attacker using PTR
  DNS records could inject data in authentication HTTP requests, as
  well as in the XCLIENT command in the SMTP connection to the proxied
  server
  ([CVE-2026-28753](https://nvd.nist.gov/vuln/detail/CVE-2026-28753));
  the fix was ported from nginx 1.29.7.



#### Bugfixes

- Rare system errors before the connection to the proxied
  server might affect the peer status correctness in [HTTP](https://en.angie.software//angie/docs/configuration/modules/index.md#modules-http)
  and [Stream](https://en.angie.software//angie/docs/configuration/modules/index.md#modules-stream) modules; they might also lead to the crash
  of a worker process in the [Stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) module;
  the bug had appeared in 1.9.1.
- In configurations where the [proxy_http_version](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http-version) `3` and
  [proxy_set_header](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-set-header) `Host ..` directives were inherited from the
  `http` block, outgoing HTTP/3 requests might be sent without the
  `Host` header.



#### Packages

- Updated:
  - [angie-pro-module-auth-jwt](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-jwt.md#external-auth-jwt), to version 0.11.0
  - [angie-pro-module-cache-purge](https://en.angie.software//angie/docs/configuration/modules/external-modules/cache-purge.md#external-cache-purge), to version 2.5.6
  - [angie-pro-module-cgi](https://en.angie.software//angie/docs/configuration/modules/external-modules/cgi.md#external-cgi), to version v0.15
  - [angie-pro-module-njs](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs), to version 0.9.6
  - [angie-pro-module-opentracing](https://en.angie.software//angie/docs/configuration/modules/external-modules/opentracing.md#external-opentracing), to version v0.43.0



### Angie PRO 1.11.3

Release date: 06.02.2026.



#### Security

- An attacker in a man-in-the-middle (MITM) position before a proxied server
  using TLS, given conditions beyond the attacker's control, could inject
  plaintext data into the response before the TLS handshake begins
  ([CVE-2026-1642](https://nvd.nist.gov/vuln/detail/CVE-2026-1642));
  the fix was ported from nginx 1.29.5.



#### Packages

- Updated:
  - [angie-pro-module-jwt](https://en.angie.software//angie/docs/configuration/modules/external-modules/jwt.md#external-jwt), to version 3.4.4



### Angie PRO 1.11.2

Release date: 15.01.2026.



#### Bugfixes

- If BPF was disabled, HTTP/3 requests might fail with an error
  `[alert] sendmsg() failed (90: Message too large) while sending frames`;
  the bug had appeared in 1.11.0.
- HTTP/3 requests were not accepted when listening on an IPv6
  wildcard address with BPF enabled;
  the bug had appeared in 1.11.0.
- When a domain name was specified in the [docker_endpoint](https://en.angie.software//angie/docs/configuration/modules/http/http_docker.md#docker-endpoint) directive,
  connections to the Docker API and updates of the upstream server
  groups didn't occur.



#### Packages

- Updated:
  - [angie-pro-module-cache-purge](https://en.angie.software//angie/docs/configuration/modules/external-modules/cache-purge.md#external-cache-purge) to version 2.5.5

02.02.2026

- Updated:
  - [angie-pro-module-njs](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs), to version 0.9.5

## 2025



### Angie PRO 1.11.1

Release date: 30.12.2025.



#### Changes

- Now, if only port without IP is specified (default value) in
  the [acme_http_port](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-http-port) directive and there are
  `server` blocks listening on that port, HTTP challenge handling
  for the port in ACME is working only on the IP addresses configured in
  the [listen](https://en.angie.software//angie/docs/configuration/modules/http/index.md#listen) directives of these blocks; there will be no attempt
  to listen on all IP addresses, like it was before; this makes
  configuration more flexible and prevents the issue with updating from
  previous versions with configurations where there were only
  `server` blocks listening on port `80` and particular IP
  addresses.



#### Bugfixes

- HTTP/2 requests were not counted in server zone statistics;
  the bug had appeared in 1.11.0.
- When an ACME client was disabled in the configuration and had
  no previously obtained certificate, a statistics API request for that
  client could crash a worker process.
- If the `$http_host` or `$cookie_*` variables were used as
  keys in the [status_zone](https://en.angie.software//angie/docs/configuration/modules/http/index.md#status-zone) directive within the `server`
  block, HTTP/3 requests might not be counted in this status zone.



#### Packages

- Updated:
  - [angie-pro-module-vts](https://en.angie.software//angie/docs/configuration/modules/external-modules/vts.md#external-vts), to version v0.2.5



### Angie PRO 1.11.0

Release date: 24.12.2025.



#### Changes

- The `$http_host` variable in HTTP/3 requests is now
  initialized from the value of the `:authority` pseudo-header if the
  `Host` header was not passed, which is normal for clients;
  previously, differences from earlier protocol versions might cause
  issues in configurations with `$http_host`.
- If all HTTP servers in an `upstream` group are unavailable or
  returning an error, the own error page is now always returned instead
  of the response from the last server when receiving a status
  considered an error according to the
  [proxy_next_upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-next-upstream) directive
  (and similar); this ensures consistent behavior in all cases.
- The `REQUEST_METHOD` parameter in `fastcgi.conf`,
  `fastcgi_params`, `uwsgi_params`, and `scgi_params`
  configuration files now is set via the `$upstream_request_method` variable, which
  takes the value `GET` for `HEAD` requests when caching is configured;
  this prevents an issue where a `HEAD` request could previously result
  in storing an empty response, which would then be served for `GET`
  requests, since the request method is not a part of the cache key in
  common configurations.
- The maximum response size from the ACME server is now limited
  by the [acme_max_response_size](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-max-response-size) directive instead of the
  `max_cert_size=` parameter of the [acme_client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) directive; the
  default value is enough for most cases, but if a certificate update
  ends up with the `[error] too big subrequest response while sending
  to client` error message, its value should be increased.
- The default value of the [variables_hash_max_size](https://en.angie.software//angie/docs/configuration/modules/http/index.md#variables-hash-max-size) directive
  in the HTTP module was increased to `2048` in order to reduce
  possibility of a warning about suboptimal hash build due to new
  variables added during the recent years: `[warn] could not build
  optimal variables_hash, you should increase either
  variables_hash_max_size: 1024 or variables_hash_bucket_size: 64;
  ignoring variables_hash_bucket_size`.



#### Features

- The new [Metric](https://en.angie.software//angie/docs/configuration/modules/http/http_metric.md#http-metric) module enabling arbitrary, real‑time HTTP
  metrics collection with fully configurable aggregation methods
  (counters, histograms, moving averages, etc.); it allows tracking any
  request‑processing data at any stage, grouped by custom keys, and
  exposes the metrics via the `/status/http/metric_zones/` API section
  (including Prometheus support), providing a powerful built‑in
  analytics tool for the entire HTTP traffic.
- Support for ALPN validation for ACME, enabled by specifying
  `alpn` in the `challenge` parameter of the
  [acme_client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) directive;
  allows to request multi-domain certificates while keeping only the
  HTTPS port open.
- Information on ACME clients and certificate requesting
  procedure in the `/status/http/acme_clients/` section of the
  statistics API (with Prometheus support).
- Added support for Encrypted Client Hello (ECH) in HTTP and
  stream SSL modules; the new [ssl_encrypted_hello_key](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-encrypted-hello-key) directive
  specifies the file with the private key; the `$ssl_encrypted_hello`
  variable contains information about ECH usage.
  Thanks to Maxim Dounin (freenginx).
- Conversion of the image format using the `convert` parameter
  for the [image_filter](https://en.angie.software//angie/docs/configuration/modules/http/http_image_filter.md#id1) directive.
- Support for AVIF and HEIC formats in the Image Filter
  module.
- Support for PROXY protocol V2 with upstream server
  connections in the stream module and the ability to set arbitrary TLV
  values using the [proxy_protocol_tlv](https://en.angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-protocol-tlv) directive which allows a string
  with variables.
- The `$upstream_request_method` variable that contains the
  upstream request method, which can be different from the client
  request method when caching is enabled or the
  [proxy_method](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-method) is set;
  this helps avoid the common configuration issue where a cached empty
  `HEAD` response is served for `GET` requests, as well as avoid caching
  `HEAD` and `GET` responses separately.
- The [sticky](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-sticky) mode, in which sessions are stored only on a
  remote server and always requested from it, is also now available in
  the `stream` module; previously, it was available only in HTTP.
- In the [sticky](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-sticky) session mode with a remote store, the response
  body is now also processed; this allows extraction of binding
  information also from the body of external storage response and not
  only from header fields.
- Removed the need to define a separate `server` block with a
  `listen 80` directive for ACME HTTP challenges; the listening port
  can be customized using the [acme_http_port](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-http-port) directive if
  necessary.
- Ability to count the number of items in lists and objects
  when exporting Prometheus metrics; paths ending with a trailing slash
  now return the count of items in the corresponding API collection.
- The `$sent_body` variable containing the response body of a
  subrequest or external request by client module.
- XOAUTH2 and OAUTHBEARER authentication mechanisms support in
  the mail proxy module.
  Thanks to Rob Mueller and Maxim Dounin (freenginx).
- The `route` parameter of the [sticky](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky) directive may now
  include arbitrary strings with any number of variables.
- In the ACME module, the approximate size of a renewed
  certificate is now calculated automatically, eliminating the need to
  increase the `max_cert_size` parameter of the
  [acme_client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) directive
  when issuing a certificate with a very large number of domains; the
  parameter is retained for cases where manual configuration is still
  required.
- Information about the license and limitations in the
  `/status/angie/license` section of the API.
- The `$upstream_cache_key` variable that contains the cache
  key being used.
  Thanks to Kirill A. Korinsky and Maxim Dounin (freenginx).
- All functionality of nginx 1.29.3 except the
  `add_header_inherit` and `add_trailer_inherit` directives, which are
  omitted due to their poor design.



#### Bugfixes

- Reload and binary upgrade procedures are now working
  correctly with HTTP/3 connections; connections are properly routed to
  all existing processes using the BPF module.
- If all servers in an `upstream` group were unavailable or
  returning an error, then receiving an erroneous response from the
  last one might be considered a success despite the
  [proxy_next_upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-next-upstream) directive settings.
- If path in the [try_files](https://en.angie.software//angie/docs/configuration/modules/http/index.md#try-files) directive was shorter than a
  prefix in the relevant `location` block, then using a
  [proxy_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass) with a URI could crash a worker process; the fix was ported from
  nginx 1.29.4.
- If an ACME client was not referenced in a `stream` block via
  any `acme` directive, using any of the corresponding
  `$acme_cert_*` variables in that block would cause the configuration to be rejected
  with an `unknown variable` error; the bug had appeared in 1.10.3.
- If preserving of the cache index to a file was configured,
  the configuration test during operation might end with errors
  `[alert] mmap() failed (17: File exists)` and `[alert] munmap()
  failed (22: Invalid argument)`.
- The [proxy_method](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-method) directive was ignored if
  `proxy_cache_convert_head on` was triggered.
- The duration of the time-out specified by the `fail_timeout`
  option of the `server` directive within an `upstream` block was
  actually one second longer.
- Loading modules built for open-source Angie version could
  cause issues and crashes due to ABI incompatibility; now such
  incorrect configurations are prohibited with a relevant error
  message.



#### Packages

- Updated:
  - [angie-pro-module-echo](https://en.angie.software//angie/docs/configuration/modules/external-modules/echo.md#external-echo), to version v0.64



### Angie PRO 1.10.3

Release date: 13.11.2025.



#### Security

- Processing of a specially crafted login/password when using
  the `none` authentication method in the SMTP module might cause
  worker process memory disclosure to the authentication server
  ([CVE-2025-53859](https://nvd.nist.gov/vuln/detail/CVE-2025-53859)); the fix was ported from nginx 1.29.1.



#### Bugfixes

- When the `renew_on_load` option of the [acme_client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client)
  directive was used, a previously obtained certificate would not be
  loaded if it existed. This could limit functionality until the
  certificate renewal was completed. If the certificate did not exist,
  attempts to obtain a new one would fail with the error `[alert]
  lseek() failed (9: Bad file descriptor)`.
- If an [ACME client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#id1) was referenced in the `stream` block but
  not the `http` block, it was disabled with the warning `[warn] ACME
  client ... is defined but not used` and would never fetch a
  certificate.
- If all [acme_client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) directives had the `enabled=off`
  parameter and the relevant `$acme_cert_*` variables were used in the
  configuration, Angie would not start, reporting the error `[emerg]
  unknown acme_cert_* variable`.
- If the [ACME client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#id1) was used in the `stream` block that came
  before an `http` block, then Angie did not start, reporting the error
  `[emerg] ACME client .. is not defined but referenced`.
- Some `client` block configurations might cause worker
  processes to crash when using variables that refer to an incoming
  connection missing in this case.
- Servers added by the [Docker](https://en.angie.software//angie/docs/configuration/modules/http/http_docker.md#http-docker) module to upstream groups were
  not monitored by active probes.
- The `send=` parameter of the [upstream_probe (PRO)](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe) directive in
  the stream module worked incorrectly for UDP probes when a file path
  was specified: instead of file content, the path was sent.
- If the `learn` option of the [sticky](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-sticky) directive was used and
  the configuration was reloaded, the `timeout=` parameter might not
  work until at least one new session was created.



#### Packages

- Updated:
  - [angie-pro-module-cache-purge](https://en.angie.software//angie/docs/configuration/modules/external-modules/cache-purge.md#external-cache-purge), to version 2.5.4
  - [angie-pro-module-cgi](https://en.angie.software//angie/docs/configuration/modules/external-modules/cgi.md#external-cgi), to version v0.14.1
  - [angie-pro-module-lua](https://en.angie.software//angie/docs/configuration/modules/external-modules/lua.md#external-lua), to version 0.10.29
  - [angie-pro-module-njs](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs), to version 0.9.4

---



### Angie PRO 1.10.2

Release date: 21.08.2025.



#### Bugfixes

- Proxy module settings in the `http` block could break
  functionality of modules that use the `client` block for outgoing
  requests; the bug had appeared in 1.10.0.
- Enabling [proxy_ignore_client_abort](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ignore-client-abort) together with modules
  that use the `client` block for outgoing requests could lead to
  worker process crashes; the bug had appeared in 1.10.0.
- If a single server was pre-configured in an upstream group,
  servers added via the [Docker API](https://en.angie.software//angie/docs/configuration/modules/http/http_docker.md#http-docker) might not be included in load
  balancing.
- If the only server in an upstream group was added via the
  [Docker API](https://en.angie.software//angie/docs/configuration/modules/http/http_docker.md#http-docker), it might be excluded from load balancing when detected to
  be unavailable.



#### Packages

- Dynamic modules added:
  - [angie-pro-module-auth-totp](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-totp.md#external-auth-totp)
  - [angie-pro-module-combined-upstreams](https://en.angie.software//angie/docs/configuration/modules/external-modules/combined-upstreams.md#external-combined-upstreams)
- Updated:
  - [angie-pro-module-opentracing](https://en.angie.software//angie/docs/configuration/modules/external-modules/opentracing.md#external-opentracing), to version 0.41.0

---



### Angie PRO 1.10.1

Release date: 17.07.2025.



#### Changes

- Directives specified in the `client` block can now only be inherited by
  explicitly declared `location` blocks within that block, so they don't
  affect the configuration of other modules that implicitly use the
  `client` block for outgoing requests.



#### Features

- Support for multiple `client` blocks allows common settings for
  different `location` blocks to be grouped within each block, which
  mitigates configuration duplication.



#### Bugfixes

- When the `reuseport` parameter was used in the `listen` directive,
  all connections to the specified address and port were handled by a single
  worker process; the bug had appeared in version 1.10.0.
- Accessing special `$stream_*` variables outside of the `stream`
  sticky session request context caused a worker process crash.
- An HTTP/3 handshake with an upstream server might fail with OpenSSL library
  version 3.5.0 or later if the QUIC protocol `retry` mode was active on
  the server.

---



### Angie PRO 1.10.0

Release date: 03.07.2025.



#### Features

- Automatic retrieval and dynamic updating of proxied server groups based on
  Docker (or Podman) container labels, configured using the
  [docker_endpoint](https://en.angie.software//angie/docs/configuration/modules/http/http_docker.md#docker-endpoint) directive. This enables real-time monitoring of
  container start and stop events via the specified Docker API endpoint,
  and allows their addresses to be added to or removed from the `upstream`
  list according to the specified labels, without requiring a configuration reload.
- Support for automatic TLS certificate acquisition via the ACME protocol in the
  `stream` module, configured using the [acme](https://en.angie.software//angie/docs/configuration/modules/stream/stream_acme.md#s-acme) directive and variables
  like [$acme_cert_\*](https://en.angie.software//angie/docs/configuration/modules/stream/stream_acme.md#v-s-acme-cert-name) and
  [$acme_cert_key_\*](https://en.angie.software//angie/docs/configuration/modules/stream/stream_acme.md#v-s-acme-cert-key-name).
- Binding of `stream` sessions for a group of proxied servers with an HTTP
  request to external storage, configurable via the [sticky](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-sticky) directive
  in `learn` mode with parameters `remote_action`,
  `remote_result`, and `remote_uri`. This enables client session persistence
  to load-balanced servers in clustered environments where a group of load balancers
  shares common storage and routes client requests within a session to the same
  server, regardless of which balancer receives the request.
- The new `norefresh` parameter for the `sticky` directive
  (in `learn` mode) disables automatic session renewal on use.
- New session mode for [sticky](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky), in which sessions are stored only
  on a remote server and are always retrieved from it. Caching of remote server
  responses can be flexibly configured in the proxy module.
- Ability to keep backup `stream` servers active even after the main server
  group becomes available again, using the `backup_switch permanent[=timeout]`
  directive in the [upstream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-upstream) block.
- Support for accepting connections via the MPTCP protocol using the `multipath`
  parameter in the [listen](https://en.angie.software//angie/docs/configuration/modules/http/index.md#listen) directive.
  Thanks to Maxim Dounin (freenginx), Maxime Dourov, and Anthony Doeraene.
- New [client](https://en.angie.software//angie/docs/configuration/modules/http/index.md#client) block for specifying additional configuration for
  internal HTTP requests initiated by various modules.
- Includes all features from [nginx 1.27.5](https://nginx.org/en/CHANGES),
  including CUBIC congestion control for QUIC connections.



#### Bugfixes

- For upstream servers in `drain` mode, the downtime counter in the
  statistics API did not stop after the server became available again according to
  passive health checks.



#### Packages

- Updated:
  - [angie-pro-console-light](https://en.angie.software//angie/docs/installation/pro_packages.md#install-console-light-pro), to version 1.8.0
  - [angie-pro-module-cgi](https://en.angie.software//angie/docs/configuration/modules/external-modules/cgi.md#external-cgi), to version 0.13
  - [angie-pro-module-otel](https://en.angie.software//angie/docs/configuration/modules/external-modules/otel.md#external-otel), to version 0.1.2

14.07.2025

- Updated:
  - [angie-pro-module-headers-more](https://en.angie.software//angie/docs/configuration/modules/external-modules/headers-more.md#external-headers-more), to version v0.39
  - [angie-pro-module-njs](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs),
    [angie-pro-module-njs-light](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs), to version 0.9.1

---



### Angie PRO 1.9.1

Release date: 29.05.2025.



#### Features

- Support for IP addresses along with port numbers in the [acme_dns_port](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-dns-port)
  directive; both IPv4 and IPv6 are allowed.



#### Bugfixes

- Using both a wildcard domain and matching third-level domains in
  [server_name](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server-name) directives could cause the ACME server to fail when issuing
  a certificate for these domains under a single ACME client.
- In the `stream` module, after a successful connection to the proxied
  server during a passive check, its status in the statistics API was
  erroneously displayed as `unavailable` until the session ended.
- The downtime counter in the statistics API might have stopped or been
  incorrectly reset while the proxied server in the `stream` module was in
  the `unhealthy` state.
- HTTP/3 requests might stall and time out; the fix was ported from nginx
  1.29.0.
- An early error while establishing an HTTP/3 connection to a proxied server
  could cause a worker process to crash.
- When proxying via the HTTP/3 protocol, the number of active connections
  in the statistics could be displayed incorrectly.
- When the proxied server in `drain` mode became unavailable, the attempt
  to connect to another server, according to the [proxy_next_upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-next-upstream) and
  similar directives, might not have occurred.



#### Packages

- Dynamic modules added:
  - [angie-pro-module-njs-light](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs)
- Updated:
  - [angie-pro-module-auth-spnego](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-spnego.md#external-auth-spnego), to version 1.1.3
  - [angie-pro-module-cgi](https://en.angie.software//angie/docs/configuration/modules/external-modules/cgi.md#external-cgi), to version 0.12.1
  - [angie-pro-module-modsecurity](https://en.angie.software//angie/docs/configuration/modules/external-modules/modsecurity.md#external-modsec), to version 1.0.4
  - [angie-pro-module-njs](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs), to version 0.9.0
  - [angie-pro-module-opentracing](https://en.angie.software//angie/docs/configuration/modules/external-modules/opentracing.md#external-opentracing), to version 0.40.0

---



### Angie PRO 1.9.0

Release date: 11.04.2025.



#### Features

- The ability to specify a file in the [proxy_cache_path](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-path) directive, where
  the contents of the shared memory zone with the cache index will be saved
  between server startups; this eliminates the need to reload the cache after a
  restart and allows the server to come back online almost immediately.
- Using the [backup_switch permanent[=timeout]](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-backup-switch) directive
  in the `upstream` block of the HTTP module allows a group of backup
  servers to remain active when the main group servers become accessible again.
- Support of TLS 1.3 Early Data (0-RTT) in the `stream` module using the
  [ssl_early_data](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#s-ssl-early-data) directive.
- New `busy` state for upstream peers in the statistics API, indicating
  that a peer has reached the limit configured by the `max_conns` option.
- The `uri=` parameter in the [acme_hook](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-hook) directive allows redefining
  the hook request URI and supports variables.
- The `renew_on_load` parameter of the [acme_client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) directive allows
  forcing certificate renewal on config load.
- Build time is now displayed via the `build_time` field of the
  `/status/angie` statistics API object and in the output of the
  `-V` command-line option.
- All functionality of [nginx 1.27.4](https://nginx.org/en/CHANGES), except
  for the `keepalive_min_timeout` directive (a similar feature has existed
  since version 1.8.0).



#### Changes

- The `enabled=off` parameter in the [acme_client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) directive now
  disables only certificate renewal for the given client while preserving all
  other functionality; the key and certificate (if available) can be accessed
  via the `$acme_cert_*` variables, while the use of `$acme_hook_*`
  variables and the `acme` directives doesn't cause errors.
- The `no valid domain name defined for ACME client` error is now issued
  only if no valid (i.e., ACME-compliant) domain name is found in the
  `server` block that references an ACME client using the `acme`
  directive.



#### Bugfixes

- If built with NTLS support, inheritance of the `proxy_ssl_certificate`
  and `proxy_ssl_certificate_key` directives with variables did not work
  properly.



#### Packages

- Updated:
  - [angie-pro-module-cgi](https://en.angie.software//angie/docs/configuration/modules/external-modules/cgi.md#external-cgi), to version 0.11.1
  - [angie-pro-module-njs](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs), to version 0.8.10

---



### Angie PRO 1.8.3

Release date: 02.04.2025.



#### Bugfixes

- The [status_zone](https://en.angie.software//angie/docs/configuration/modules/http/index.md#status-zone) statistics in the HTTP module's [server](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server) block could be
  miscalculated if requests within the same connection belonged to different
  statistics zones, or if an error occurred during early request processing; the
  bug had appeared in 1.8.2.



#### Packages

- Updated:
  - [angie-pro-console-light](https://en.angie.software//angie/docs/installation/pro_packages.md#install-console-light-pro), to version 1.7.0
  - [angie-pro-module-cgi](https://en.angie.software//angie/docs/configuration/modules/external-modules/cgi.md#external-cgi), to version 57f660bb2c6ef6e4b75c65406080d0236860ca08
  - [angie-pro-module-jwt](https://en.angie.software//angie/docs/configuration/modules/external-modules/jwt.md#external-jwt), to version v3.4.3
  - [angie-pro-module-ndk](https://en.angie.software//angie/docs/configuration/modules/external-modules/ndk.md#external-ndk), to version v0.3.4
  - [angie-pro-module-opentracing](https://en.angie.software//angie/docs/configuration/modules/external-modules/opentracing.md#external-opentracing), to version v0.39.0
  - [angie-pro-module-vts](https://en.angie.software//angie/docs/configuration/modules/external-modules/vts.md#external-vts), to version v0.2.4

04.04.2025

- Updated:
  - [angie-pro-console-light](https://en.angie.software//angie/docs/installation/pro_packages.md#install-console-light-pro), to version 1.7.1

07.04.2025

- Updated:
  - [angie-pro-console-light](https://en.angie.software//angie/docs/installation/pro_packages.md#install-console-light-pro), to version 1.7.2



### Angie PRO 1.8.2

Release date: 13.02.2025.



#### Security

- Insufficient validation while handling virtual servers with TLSv1.3 SNI
  allowed SSL sessions to be reused in a different virtual server,
  bypassing client SSL certificate verification ([CVE-2025-23419](https://www.cve.org/CVERecord?id=CVE-2025-23419));
  the fix was ported from nginx 1.27.4.



#### Bugfixes

- Active probes configured with the [upstream_probe (PRO)](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe) directive
  in the `stream` module could cause a worker process to crash.
- API requests to retrieve statistic values from an individual zone,
  which was set via variables,
  could cause a worker process to enter an infinite loop.
- HTTP/3 requests were not counted in zone statistics;
  the bug had appeared in 1.8.0.
- TLS handshakes using QUIC protocol were not counted in SSL statistics.
- Certificate renewal via the [ACME protocol](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#id1) could fail
  for server names prefixed with a dot in the [server_name](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server-name) directive.



#### Packages

- Dynamic modules added:
  - [angie-pro-module-auth-pam](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-pam.md#external-auth-pam)
  - [angie-pro-module-cgi](https://en.angie.software//angie/docs/configuration/modules/external-modules/cgi.md#external-cgi)

---

## 2024



### Angie PRO 1.8.1

Release date: 28.12.2024.

#### Bugfixes

- Using the [status_zone](https://en.angie.software//angie/docs/configuration/modules/http/index.md#status-zone) directive in the `server` block of the
  HTTP module caused excessive logging of empty requests in [access_log](https://en.angie.software//angie/docs/configuration/modules/http/http_log.md#access-log) on
  TLS handshakes; the bug had appeared in 1.8.0.
- Decoding errors in HTTP/3 stream could cause a worker process crash when
  closing a QUIC connection; the fix was ported from nginx 1.27.4.
- Sending QUIC protocol version negotiation packets could cause an infinite
  packet exchange loop; the fix was ported from nginx 1.27.4.
- Using DNS-challenge without hooks in the [ACME](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme) module could
  cause a worker process crash in some configurations.



#### Packages

- Updated:
  - [angie-pro-module-auth-jwt](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-jwt.md#external-auth-jwt), to version 0.9.0

23.01.2025

- Updated:
  - [angie-pro-console-light](https://en.angie.software//angie/docs/installation/pro_packages.md#install-console-light-pro), to version 1.6.0

27.01.2025

- Dynamic modules added:
  - [angie-pro-module-unbrotli](https://en.angie.software//angie/docs/configuration/modules/external-modules/unbrotli.md#external-unbrotli)
- Updated:
  - [angie-pro-console-light](https://en.angie.software//angie/docs/installation/pro_packages.md#install-console-light-pro), to version 1.6.1
  - [angie-pro-module-auth-spnego](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-spnego.md#external-auth-spnego), to version v1.1.2
  - [angie-pro-module-headers-more](https://en.angie.software//angie/docs/configuration/modules/external-modules/headers-more.md#external-headers-more), to version v0.38
  - [angie-pro-module-lua](https://en.angie.software//angie/docs/configuration/modules/external-modules/lua.md#external-lua), to version 0.10.28
  - [angie-pro-module-njs](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs), to version 0.8.9
  - [angie-pro-module-vts](https://en.angie.software//angie/docs/configuration/modules/external-modules/vts.md#external-vts), to version v0.2.3
  - [angie-pro-module-wasm](https://en.angie.software//angie/docs/configuration/modules/wasm/index.md#wasm-core), to version v0.2-beta2

---



### Angie PRO 1.8.0

Release date: 19.12.2024.



#### Features

- HTTP session binding for a group of proxied servers with a request to external
  storage, configurable by the [sticky](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky) directive in the `learn`
  mode using the `remote_action` and `remote_result` parameters;
  this allows to configure binding of client sessions to balanced servers in
  cluster mode, when a group of balancers is unified by shared storage and
  directs client requests within one session to the same server regardless of
  which balancer they hit.
- Support of `DNS-01` challenges by handling DNS queries from the ACME
  server, which allows to automatically request certificates of any types,
  including wildcard ones.
- Hooks system in the ACME module, configurable using the [acme_hook](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-hook)
  directive, which allows handling of domain name challenges using an external
  application to provide integration with various services and DNS hosting
  providers.
- The ACME module logs some additional information: why exactly the certificate
  is being renewed, full domain name list, client's account ID, long periods of
  inactivity (e.g. pollings), and the domain name being challenged; this
  information simplifies troubleshooting and allows to specify the CAA DNS
  record.
- The `account_key` parameter of the [acme_client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) directive, which
  allows to reuse an existing key for the ACME server account instead of
  auto-generating a new one.
- Support for variables in the [status_zone](https://en.angie.software//angie/docs/configuration/modules/http/index.md#status-zone) directives in the stream and
  HTTP modules allows to dynamically account statistics within several zones in
  a single `location` or `server` block; in particular, it's
  especially useful when a single `server` block is handling multiple
  virtual hosts.
- GZip HTTP compression module compatibility with the `zlib-ng` versions
  2.2.0 and above, which could previously cause `[alert] gzip filter
  failed to use preallocated memory` messages in the error log.
- The [max_headers](https://en.angie.software//angie/docs/configuration/modules/http/index.md#max-headers) directive that limits the number of HTTP request header
  fields to better protect against DoS attacks. Thanks to Maxim Dounin
  (freenginx) and Maksim Yevmenkin.
- The [http3_max_table_capacity](https://en.angie.software//angie/docs/configuration/modules/http/http_v3.md#http3-max-table-capacity) and [proxy_http3_max_table_capacity](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http3-max-table-capacity)
  directives to configure the HTTP/3 dynamic header compression table limits.
- Cross-compilation support - the build system can now use a wrapper script to
  run autotests, which enables to prepare a build without running test programs
  directly on the target platform.
- All functionality of [nginx 1.27.3](https://nginx.org/en/CHANGES).

#### Bugfixes

- HTTP/3 clients could time out when using `0-RTT`; the bug was inherited
  from nginx in version 1.7.0.
- Proxying with HTTP/3 using variables in the [proxy_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass) directive and
  without specifying an `upstream` block could crash the worker process.
- HTTP/3 upstreams using dynamic table could lead to worker process crash if
  used with cache.
- Some SSL handshakes could be not counted in statistics for the `stream`
  module.
- HTTP/3 proxy settings specified in `http` or `server` level might
  be ignored.
- The [proxy_ssl_certificate](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ssl-certificate) directive didn't work when proxying via
  HTTP/3 with NTLS support enabled.



#### Changes

- When gracefully shutting down old worker processes, keep-alive connections are
  now closed only after the timeout specified by the [lingering_timeout](https://en.angie.software//angie/docs/configuration/modules/http/index.md#lingering-timeout)
  directive has expired; this behaviour allows to avoid possible client errors
  when receiving replies at that moment. Thanks to Maxim Dounin (freenginx).
- Disabled caching of the `stream` module variables
  [$ssl_server_name](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-server-name), [$ssl_server_cert_type](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-server-cert-type),
  [$ssl_preread_protocol](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl_preread.md#v-ssl-preread-protocol), and [$ssl_preread_server_name](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl_preread.md#v-ssl-preread-server-name), which
  allows to get actual values when using virtual servers.

#### Packages

- Dynamic modules added:
  - [angie-pro-module-http-auth-radius](https://en.angie.software//angie/docs/configuration/modules/external-modules/http-auth-radius.md#external-http-auth-radius)
- Updated:
  - [angie-pro-module-auth-jwt](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-jwt.md#external-auth-jwt), to version 0.8.0
  - [angie-pro-module-jwt](https://en.angie.software//angie/docs/configuration/modules/external-modules/jwt.md#external-jwt), to version 3.4.2
  - [angie-pro-module-njs](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs), to version 0.8.8
  - [angie-pro-module-opentracing](https://en.angie.software//angie/docs/configuration/modules/external-modules/opentracing.md#external-opentracing), to version 0.38.0
  - [angie-pro-module-wasm](https://en.angie.software//angie/docs/configuration/modules/wasm/index.md#wasm-core), to version 0.1-beta5

---



### Angie PRO 1.7.0

Release date: 19.09.2024.



#### Features

- Forced closing all the connections to a proxied server when it's removed from
  the group; it can be configured via the [proxy_connection_drop](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-connection-drop),
  [grpc_connection_drop](https://en.angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-connection-drop), [fastcgi_connection_drop](https://en.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-connection-drop),
  [scgi_connection_drop](https://en.angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-connection-drop), and [uwsgi_connection_drop](https://en.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-connection-drop) directives,
  which value can be overridden locally with the `connection_drop`
  argument of an [API request](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-config-methods) for server removal.
- Counters of sent DNS query types in the resolver statistics API, which is
  collected with the `status_zone` parameter of the [resolver](https://en.angie.software//angie/docs/configuration/modules/http/index.md#resolver)
  directive.
- The [feedback (PRO)](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-feedback) load balancing now can be used in the `stream`
  module; it distributes TCP/UDP sessions based on a specified variable, which
  can be obtained from proxied upstream servers or periodic requests to external
  services. This allows dynamic load balancing depending on arbitrary metrics of
  proxied servers, such as resource consumption, CPU/memory utilization, and
  queue length.
- The `last_byte` option of the [feedback (PRO)](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-feedback) directive, which allows
  processing upstream server feedback after the entire response is received,
  rather than only the header.
- The [feedback (PRO)](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-feedback) load balancing method now accepts
  floating-point numbers as the variable value.
- The `account` parameter of the [least_time](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-least-time) directive, which
  enables using a variable to specify which requests are considered for
  `least_time` balancing, including considering only [upstream_probe (PRO)](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe)
  requests.
- The `factor` parameter of the [least_time](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-least-time) directive, which
  allows to specify an adjustable smoothing factor for the `least_time`
  balancer and overrides the value of the [response_time_factor](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-response-time-factor) used
  for statistics collection.
- A `drain` mode that switches the proxied stream server to a new
  `draining` state, when only requests bound using the [sticky](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-sticky)
  module are sent to the server.
- The [$ssl_server_cert_type](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-server-cert-type) variable that contains the type of selected
  certificate for a received TLS-connection.
- Disabling creation of the PID file with the `off` parameter of the
  [pid](https://en.angie.software//angie/docs/configuration/modules/core.md#pid) directive, which might be beneficial with immutable images and
  direct control by a service manager. Thanks to Maxim Dounin (freenginx).
- Creation of the PID file made atomic via an intermediate temporary file, which
  removes a moment when the file is already in the directory but still empty,
  and allows external programs to handle it more easily and reliably.
- Now, during reconfiguration, no attempt is made to recreate the PID file if
  the name in the [pid](https://en.angie.software//angie/docs/configuration/modules/core.md#pid) directive has changed but points to the same file
  via symlinks; in particular, it allows avoiding issues on systems that migrate
  from `/var/run/angie.pid` to `/run/angie.pid`. Thanks to Maxim
  Dounin (freenginx).
- [Syslog logging](https://en.angie.software//angie/docs/configuration/processing.md#syslog-logging) errors are now reported no more than
  once per second; this helps avoid flooding the logs with such messages when
  the syslog server is down or overloaded. Thanks to Maxim Dounin (freenginx).
- In the Mail proxy module, the maximum number of commands during
  authentication, configured with the [max_commands](https://en.angie.software//angie/docs/configuration/modules/mail/index.md#max-commands) directive, is limited
  to better protect against DoS attacks. Thanks to Maxim Dounin (freenginx).
- The [--feature-cache](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure) option of the
  **./configure** script to cache its results for optimization when
  building multiple modules or cross-compiling.
- All functionality of [nginx 1.27.1](https://nginx.org/en/CHANGES).

#### Bugfixes

- The wait timeout of a queued request configured by the [queue (PRO)](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-queue)
  directive could crash the worker process.
- `PID file ... not readable (yet?) after start` and `Failed to
  parse PID from file...` errors might appear when starting with
  **systemd**. Thanks to Maxim Dounin (freenginx).



#### Changes

- Updated descriptions of HTTP status codes in conformance with RFC 9110. Thanks
  to Maxim Dounin (freenginx) and Michiel W. Beijen.
- A maximum of one empty line is now allowed before an HTTP request to better
  protect against DoS attacks. Thanks to Maxim Dounin (freenginx).
- HTTP/1.x header field names without a colon at the end are now prohibited;
  such invalid header fields from a client or a proxied server will now cause an
  error response. Thanks to Maxim Dounin (freenginx) and Maksim Yevmenkin.
- When reading a request body using HTTP/1.1 chunked transfer encoding, the
  total size of ignored chunk extensions and trailer header fields is now
  limited by the [client_max_body_size](https://en.angie.software//angie/docs/configuration/modules/http/index.md#client-max-body-size) directive to better protect against
  DoS attacks. Thanks to Maxim Dounin (freenginx) and Bartek Nowotarski.
- The MIME type in the `mime.types` configuration file has been changed to
  `image/bmp` for the `bmp` extension and
  `application/vnd.rar` for the `rar` extension; set to
  `application/vnd.debian.binary-package` for the `deb` and
  `udeb` extensions. Thanks to Yuriy Izorkin.

#### Packages

- Updated:
  - [angie-pro-module-opentracing](https://en.angie.software//angie/docs/configuration/modules/external-modules/opentracing.md#external-opentracing), to version 0.36.0
  - [angie-pro-module-lua](https://en.angie.software//angie/docs/configuration/modules/external-modules/lua.md#external-lua), to version 0.10.27

24.10.2024

- Added packages for [SberLinux](https://en.angie.software//angie/docs/installation/pro_packages.md#install-yum-pro).

---



### Angie PRO 1.6.2

Release date: 16.08.2024.



#### Security

- Processing a specially crafted MP4 file with the
  [MP4](https://en.angie.software//angie/docs/configuration/modules/http/http_mp4.md#http-mp4)
  could cause a worker process crash
  ([CVE-2024-7347](https://nvd.nist.gov/vuln/detail/CVE-2024-7347));
  the fix was ported from nginx 1.27.1.

---



### Angie PRO 1.6.1

Release date: 08.08.2024.



#### Features

- A new `passed` counter in the
  [API statistics](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-stream-server-zones) zone
  configured by the [status_zone](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#s-status-zone) directive
  of the [Stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) module
  tracks connections passed to other listening sockets
  using [pass](https://en.angie.software//angie/docs/configuration/modules/stream/stream_pass.md#s-pass) directives.

#### Bugfixes

- When using virtual servers or the [pass](https://en.angie.software//angie/docs/configuration/modules/stream/stream_pass.md#s-pass) directive in the
  [Stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) module,
  connections could be accounted incorrectly in the statistics API.
- Worker processes could crash on configurations with 5 or more ACME
  clients; the bug had appeared in 1.6.0.
- Handling cached responses with the `X-Accel-Redirect` header
  could crash the worker process.
  Thanks to Maxim Dounin (freenginx) and Jiří Setnička.

#### Packages

- Updated:
  - [angie-pro-console-light](https://en.angie.software//angie/docs/installation/pro_packages.md#install-console-light-pro), to version 1.4.0
  - [angie-pro-module-opentracing](https://en.angie.software//angie/docs/configuration/modules/external-modules/opentracing.md#external-opentracing), to version 0.35.3
  - [angie-pro-module-zstd](https://en.angie.software//angie/docs/configuration/modules/external-modules/zstd.md#external-zstd), to revision `f4ba115`

---



### Angie PRO 1.6.0

Release date: 28.06.2024.



#### Features

- HTTP request balancing based on the value of a specified variable
  which can be obtained from proxied servers
  or periodic polling of external services,
  configured using the [feedback](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-feedback) directive
  in the [upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) block;
  this allows, in particular, to dynamically redistribute the load
  depending on arbitrary metrics of the proxied server:
  consumption of various resources, CPU/memory utilization, queue length, etc.
- The [sticky](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-sticky) directive and related settings
  in the [upstream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-upstream) block of the [Stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) module,
  which allow configuring session persistence mode
  where all connections within a session are routed to the same server.
- Extraction of Cookie values from RDP connections using the
  [rdp_preread](https://en.angie.software//angie/docs/configuration/modules/stream/stream_rdp_preread.md#s-rdp-preread) directive of the [Stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) module
  into [$rdp_cookie](https://en.angie.software//angie/docs/configuration/modules/stream/stream_rdp_preread.md#v-rdp-cookie) and [$rdp_cookie_NAME](https://en.angie.software//angie/docs/configuration/modules/stream/stream_rdp_preread.md#id3) variables,
  which allows logging and binding RDP client sessions to the same servers
  when load balancing.
- The `persistent` option
  of the [upstream_probe](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe) directive,
  which allows avoiding waiting for `essential` probes to pass
  after configuration reload for previously healthy servers.
- Support for multiple [acme](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#id1) directives
  in a single [server](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server) block,
  which allows configuring obtaining both types of certificates at once
  within that virtual server.
- Command line options `-m` and `-M`
  to display a list of built-in and loaded modules.
- The [$upstream_probe](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#v-upstream-probe) variable
  that contains the name of the current active probe
  issued by [upstream_probe](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe).
- Support for [BoringSSL](https://www.chromium.org/Home/chromium-security/boringssl/)
  in the [ACME](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme) module.
- All functionality of [nginx 1.27.0](https://nginx.org/en/CHANGES),
  including support for virtual servers in the [Stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) module
  and the `pass` directive,
  which allows passing accepted connections for handling to other listening sockets,
  including [HTTP](https://en.angie.software//angie/docs/configuration/modules/index.md#modules-http) and [Mail](https://en.angie.software//angie/docs/configuration/modules/index.md#modules-mail) modules.

#### Bugfixes

- Active [upstream_probe](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe) probes might not have worked
  on some configurations while logging error messages like
  `[alert] getsockname() failed (9: Bad file descriptor)`.
- Certificate request via the ACME protocol could fail
  on some configurations with a log message like
  `[alert] getsockname() failed (9: Bad file descriptor)`.
- Certificate request with a large number of domain names via the
  ACME protocol could fail with a log message like
  `[error] JSON parser error`.
- ACME clients in configurations
  with multiple [error_log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log) directives
  could output messages to incorrect logs.

#### Packages

- Updated:
  - [angie-pro-module-auth-jwt](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-jwt.md#external-auth-jwt), to version 0.7.0
  - [angie-pro-module-auth-ldap](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-ldap.md#external-ldap), to revision `241200e`
  - [angie-pro-module-jwt](https://en.angie.software//angie/docs/configuration/modules/external-modules/jwt.md#external-jwt), to version 3.4.1
  - [angie-pro-module-keyval](https://en.angie.software//angie/docs/configuration/modules/external-modules/keyval.md#external-keyval), to version 0.3.0
  - [angie-pro-module-lua](https://en.angie.software//angie/docs/configuration/modules/external-modules/lua.md#external-lua):
    `stream_lua_module`, to revision `bea8a0c`
  - [angie-pro-module-njs](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs), to version 0.8.5

---



### Angie PRO 1.5.2

Release date: 03.06.2024.



#### Security

- When using HTTP/3, processing a specially crafted QUIC
  session could cause a worker process crash, worker process memory
  disclosure on systems with MTU larger than 4096 bytes, or have other
  impact ([CVE-2024-32760](https://nvd.nist.gov/vuln/detail/CVE-2024-32760),
  [CVE-2024-31079](https://nvd.nist.gov/vuln/detail/CVE-2024-31079),
  [CVE-2024-35200](https://nvd.nist.gov/vuln/detail/CVE-2024-35200),
  [CVE-2024-34161](https://nvd.nist.gov/vuln/detail/CVE-2024-34161));
  the fix was ported from nginx 1.26.1.

#### Packages

- Updated:
  - [angie-pro-module-opentracing](https://en.angie.software//angie/docs/configuration/modules/external-modules/opentracing.md#external-opentracing), to version 0.35.2

---



### Angie PRO 1.5.1

Release date: 16.05.2024.

#### Bugfixes

- The `proxy_next_upstream` mechanism did not work correctly when editing
  a group of proxied servers via the API, and when using the [resolve](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-reresolve) option of the `server` directive in the
  `upstream` block if the number of
  resolved IP addresses differed from the number of specified servers.
- While requesting a certificate via the ACME protocol, a
  segmentation fault could occur in a worker process.
- The [sticky](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky) directive in the `learn` mode could work
  incorrectly with different numbers of `lookup` and `create`
  variables.
- The [slow_start](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-slow-start) mechanism did not work when proxying TCP
  connections in the [Stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) module.
- HTTP/3 requests could fail if received as TLS
  1.3 early data; the bug had appeared in 1.4.0.
- HTTP/3 connection could be prematurely closed while using
  0-RTT in QUIC.
- When reading a request body from a fast connection, reading
  for a long time was possible. Thanks to Maxim Dounin (freenginx).



#### Changes

- Now ACME clients do not discard previously stored
  certificates if they are expired or issued for a different domain list,
  but use them while renewal is in progress.

#### Packages

27.05.2024

- Added packages for [Alpine](https://en.angie.software//angie/docs/installation/pro_packages.md#install-alpine-pro) 3.20.

---



### Angie PRO 1.5.0

Release date: 27.03.2024.

#### Features

- Initial support for automatically obtaining and updating certificates using the
  [ACME protocol](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme), configurable with the
  [acme_client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) and [acme](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#id1) directives, as well as variables of the
  form [$acme_cert_=](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-cert-name) and [$acme_cert_key_=](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-cert-key-name).
- A `drain` mode that switches the proxied HTTP server to a new
  `draining` state, where only requests bound using the [sticky](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky) module are sent to the server.
- Configuration of automatic redirection that adds trailing
  slashes to request URIs using the [auto_redirect](https://en.angie.software//angie/docs/configuration/modules/http/index.md#auto-redirect) directive.
- Output of date-containing [metrics](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#metrics) in Unix timestamp format
  instead of ISO 8601 for use in Prometheus, and also in the JSON API when requested
  with the `?date-epoch` argument.
- Now the `-V` option also shows the relevant version of nginx, which is
  useful for compatibility with third-party utilities, **certbot** in
  particular. Thanks to [AdvTechnoKing](https://github.com/webserver-llc/angie/commit/eb914d43aa6a2231d7321c808cb4180abb013ca0).
- All functionality of [nginx 1.25.4](https://nginx.org/en/CHANGES).

#### Bugfixes

- If the SSL session reuse mechanism ([proxy_ssl_session_reuse](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ssl-session-reuse)) was used,
  then when dynamically updating the list of proxied servers, a leak could occur
  in the shared memory zone (`zone`) configured for the corresponding `upstream` block.

#### Packages

- Added packages for [FreeBSD 13](https://en.angie.software//angie/docs/installation/pro_packages.md#install-freebsd-pro) (arm64),
  [RED OS 8](https://en.angie.software//angie/docs/installation/pro_packages.md#install-yum-pro) (x86-64).
- Dynamic modules added:
  - [angie-pro-module-otel](https://en.angie.software//angie/docs/configuration/modules/external-modules/otel.md#external-otel)
- Updated:
  - [angie-pro-module-opentracing](https://en.angie.software//angie/docs/configuration/modules/external-modules/opentracing.md#external-opentracing), to version 0.34.0

28.03.2024

- Updated:
  - [angie-pro-console-light](https://en.angie.software//angie/docs/installation/pro_packages.md#pro-packages), to version 1.3.0

16.04.2024

- Dynamic modules added:
  - [angie-pro-module-zstd](https://en.angie.software//angie/docs/configuration/modules/external-modules/zstd.md#external-zstd)
- Updated:
  - [angie-pro-module-njs](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs), to version 0.8.4

25.04.2024

- Dynamic modules added:
  - angie-pro-module-vts: includes
    [module-vts](https://github.com/vozlt/nginx-module-vts),
    [module-sts](https://github.com/vozlt/nginx-module-sts),
    [module-stream-sts](https://github.com/vozlt/nginx-module-stream-sts)

---



### Angie PRO 1.4.1

Release date: 15.02.2024.



#### Security

- When using HTTP/3, a segmentation error could have occurred in a worker process
  while processing a specially crafted QUIC session
  ([CVE-2024-24989](https://nvd.nist.gov/vuln/detail/CVE-2024-24989));
  note that Angie PRO as of 1.4.0 is not vulnerable to
  [CVE-2024-24990](https://nvd.nist.gov/vuln/detail/CVE-2024-24990).

#### Packages

- Dynamic modules added:
  - [angie-pro-module-dynamic-limit-req](https://en.angie.software//angie/docs/configuration/modules/external-modules/dynamic-limit-req.md#external-dynamic-limit-req)
- Updated:
  - [angie-pro-module-njs](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs), to version 0.8.3
  - [angie-pro-module-vod](https://en.angie.software//angie/docs/configuration/modules/external-modules/vod.md#external-vod), to version 1.33

## 2023



### Angie PRO 1.4.0

Release date: 21.12.2023.

#### Features

- Support for establishing [HTTP/3](https://en.angie.software//angie/docs/configuration/modules/http/http_v3.md#http-v3) connections to upstream
  servers in the HTTP [Proxy](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy) module while allowing clients to
  use arbitrary HTTP versions. Configuration is done with the
  [proxy_http_version](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http-version) directive and a set of `proxy_quic_` and
  `proxy_http3_` directives.
- The [upstream_probe (PRO)](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe) directive to check the health of servers in the
  Stream [Upstream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#stream-upstream) module's `upstream` block by
  periodically creating test connections or sending datagrams.
- Additional `learn` mode of the [sticky](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky) directive for
  binding sessions to proxied servers that allows discovering sessions and saving
  them in the server's shared memory.
- Waiting queue for requests that couldn't be load-balanced on the first try,
  configured using the [queue (PRO)](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-queue) directive in the HTTP
  [Upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream) module's `upstream` block.
- HTTP RESTful [JSON interface](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-config-stream-upstreams-servers) for
  reconfiguring, adding, or deleting servers in the Stream
  [Upstream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#stream-upstream) module's `upstream` blocks, and the
  [state](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-state) directive for persisting these changes.
- Load balancing by average time to establish a connection, receive the first or
  last byte of a response from proxied [stream upstream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#stream-upstream)
  servers with an adjustable smoothing factor, using the [least_time](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-least-time)
  and [response_time_factor](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-response-time-factor) directives in the `upstream` block.
- Statistics of average time to establish a connection, receive the first and
  last byte of a response from proxied [stream upstream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#stream-upstream)
  servers in the interface provided by the [api](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#a-api) directive, with
  the ability to adjust the smoothing factor via the
  [response_time_factor](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-response-time-factor) directive of the `upstream` block.
- A mechanism for smoothly bringing a proxied server online after a failure
  using the `slow_start` option of the [server](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) directive
  in the `upstream` block.
- [mqtt_preread](https://en.angie.software//angie/docs/configuration/modules/stream/stream_mqtt_preread.md#s-mqtt-preread) directive in the Stream
  [MQTT Preread](https://en.angie.software//angie/docs/configuration/modules/stream/stream_mqtt_preread.md#stream-mqtt-preread) module, which allows extracting the
  username and client ID from the CONNECT packet of the MQTT protocol into the
  [$mqtt_preread_username](https://en.angie.software//angie/docs/configuration/modules/stream/stream_mqtt_preread.md#v-mqtt-preread-username) and
  [$mqtt_preread_clientid](https://en.angie.software//angie/docs/configuration/modules/stream/stream_mqtt_preread.md#v-mqtt-preread-clientid) variables.
- Limiting the response rate of MP4 file transmission to the client
  proportionally to the bitrate using the [mp4_limit_rate](https://en.angie.software//angie/docs/configuration/modules/http/http_mp4.md#mp4-limit-rate) and
  [mp4_limit_rate_after](https://en.angie.software//angie/docs/configuration/modules/http/http_mp4.md#mp4-limit-rate-after) directives, which reduces the bandwidth load.
- All functionality of [nginx 1.25.3](https://nginx.org/en/CHANGES).

#### Bugfixes

- If a proxied server was the only one in a group, it could be incorrectly
  reported as `unavailable` in the [statistics API](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#metrics) even
  after recovery.



#### Changes

- Now the time a proxied server spends in the `checking` state is not
  counted as `downtime`.
- The standard [prometheus_all.conf](https://en.angie.software//angie/docs/configuration/modules/http/http_prometheus.md#prometheus-all) template includes all
  additional Prometheus metrics and possible `state` values of
  `upstream` peers that are only exposed by the PRO version.

#### Packages

- Packages for [Alpine](https://en.angie.software//angie/docs/installation/pro_packages.md#install-alpine-pro) 3.19.
- Updated:
  - [angie-pro-console-light](https://en.angie.software//angie/docs/installation/pro_packages.md#pro-packages), to version 1.2.0
  - [angie-pro-module-auth-jwt](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-jwt.md#external-auth-jwt), to version 0.4.0
  - [angie-pro-module-headers-more](https://en.angie.software//angie/docs/configuration/modules/external-modules/headers-more.md#external-headers-more), to version 0.36
  - [angie-pro-module-ndk](https://en.angie.software//angie/docs/configuration/modules/external-modules/ndk.md#external-ndk), to version 0.3.3
  - [angie-pro-module-opentracing](https://en.angie.software//angie/docs/configuration/modules/external-modules/opentracing.md#external-opentracing), to version 0.33.0

25.12.2023

- Updated:
  - [angie-pro-console-light](https://en.angie.software//angie/docs/installation/pro_packages.md#pro-packages), to version 1.2.1

22.01.2024

- Dynamic modules added:
  - [angie-pro-module-zip](https://en.angie.software//angie/docs/configuration/modules/external-modules/zip.md#external-zip)
- Updated:
  - [angie-pro-module-auth-jwt](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-jwt.md#external-auth-jwt), to version 0.6.0
  - [angie-pro-module-headers-more](https://en.angie.software//angie/docs/configuration/modules/external-modules/headers-more.md#external-headers-more), to version 0.37
  - [angie-pro-module-lua](https://en.angie.software//angie/docs/configuration/modules/external-modules/lua.md#external-lua):
    `http_lua_module`, to version 0.10.26;
    `stream_lua_module`, to version 0.0.14

---



### Angie PRO 1.3.2

Release date: 23.11.2023.

#### Bugfixes

- Active [health probes](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe) with the `essential` flag
  incorrectly handled the server's transition from `checking` to
  `unhealthy` when the initial check failed, resulting in user
  requests being routed to the faulty server.
- Possible incorrect values of metrics in [Prometheus](https://en.angie.software//angie/docs/configuration/modules/http/http_prometheus.md#id1) output
  that used variables other than `$p8s_value` for their values; in
  practice the issue could occur with `angie_http_upstreams_peers_state`
  and `angie_stream_upstreams_peers_state` from the standard
  `prometheus_all.conf` template.
- Some connection attempts to upstream servers might not have been properly
  accounted for in the [statistics API](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#a-api) if they failed immediately;
  the bug had appeared in 1.3.0.

#### Packages

04.12.2023

- Dynamic modules added:
  - [angie-pro-module-modsecurity](https://github.com/owasp-modsecurity/ModSecurity-nginx)

07.12.2023

- Updated:
  - [angie-pro-console-light](https://en.angie.software//angie/docs/installation/pro_packages.md#pro-packages), to version 1.1.1

12.12.2023

- Dynamic modules added:
  - [angie-pro-module-auth-ldap](https://github.com/kvspb/nginx-auth-ldap)
- Updated:
  - [angie-pro-module-auth-jwt](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-jwt.md#external-auth-jwt), to version 0.4.0
  - [angie-pro-module-headers-more](https://en.angie.software//angie/docs/configuration/modules/external-modules/headers-more.md#external-headers-more), to version 0.36
  - [angie-pro-module-ndk](https://en.angie.software//angie/docs/configuration/modules/external-modules/ndk.md#external-ndk), to version 0.3.3
  - [angie-pro-module-opentracing](https://en.angie.software//angie/docs/configuration/modules/external-modules/opentracing.md#external-opentracing), to version 0.33.0

---



### Angie PRO 1.3.1

Release date: 18.10.2023.



#### Security

- Added extra limitations to HTTP/2 stream handling for better protection
  against the DoS attack known as "HTTP/2 Rapid Reset" ([CVE-2023-44487](https://nvd.nist.gov/vuln/detail/CVE-2023-44487)).

#### Packages

26.10.2023

- Dynamic modules added:
  - [angie-pro-module-opentracing](https://en.angie.software//angie/docs/configuration/modules/external-modules/opentracing.md#external-opentracing)

13.11.2023

- Dynamic modules added:
  - [angie-pro-module-testcookie](https://en.angie.software//angie/docs/configuration/modules/external-modules/testcookie.md#external-testcookie)
- Updated:
  - [angie-pro-console-light](https://en.angie.software//angie/docs/installation/pro_packages.md#pro-packages), to version 1.1.0
  - [angie-pro-module-headers-more](https://en.angie.software//angie/docs/configuration/modules/external-modules/headers-more.md#external-headers-more), to version 0.35
  - [angie-pro-module-njs](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs), to version 0.8.2
  - [angie-pro-module-vod](https://en.angie.software//angie/docs/configuration/modules/external-modules/vod.md#external-vod), to version 1.32

---



### Angie PRO 1.3.0

Release date: 03.10.2023.

#### Features

- Ability to specify multiple match patterns in the `location` directive,
  which allows to [combine](https://en.angie.software//angie/docs/configuration/modules/http/index.md#combined-locations) several `location`
  blocks with similar settings and therefore simplify configuration by reducing
  duplication.
- Load balancing by average time to receive the response header or full response
  from proxied HTTP servers with an adjustable smoothing factor, using the
  [least_time](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-least-time) and [response_time_factor](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-response-time-factor) directives in the
  `upstream` block.
- Export of varied statistics metrics in Prometheus format with flexible
  template configuration using the new [prometheus](https://en.angie.software//angie/docs/configuration/modules/http/http_prometheus.md#id1) and
  [prometheus_template](https://en.angie.software//angie/docs/configuration/modules/http/http_prometheus.md#prometheus-template) directives.
- Statistics of average time to receive the response header and full response of
  proxied HTTP servers in the interface provided by the [api](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#a-api) directive,
  with the ability to adjust the average smoothing factor via the
  [response_time_factor](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-response-time-factor) directive
  of the `upstream` block.
- Detailed information and [metrics](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-stream-upstreams) for
  groups of stream upstream servers in the statistics interface provided by the
  [api](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#a-api) directive.
- The [resolve](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-reresolve) option of the `server` directive in the
  Stream [Upstream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#stream-upstream) module's `upstream` block that
  allows to monitor changes to the list of IP addresses corresponding to a
  domain name, and automatically update it without the need of reloading
  configuration.
- The [service](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-reresolve) option of the `server` directive in the
  Stream [Upstream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#stream-upstream) module's `upstream` block that
  allows to retrieve lists of addresses from DNS SRV records, with basic
  priority support.
- Support for binding a client connection to a backend server connection using
  the [bind_conn (PRO)](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-bind-conn) directive in the HTTP [Upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream)
  module's `upstream` blocks, particularly for proxying connections with
  NT LAN Manager (NTLM) authentication.
- Access to the contents of configuration files used by the current generation
  of worker processes via the interface provided
  by the [api](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#a-api) directive
  with the [api_config_files](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#a-api-config-files) directive enabled.
- Display of the [configuration generation](https://en.angie.software//angie/docs/configuration/runtime.md#control-config-change) number
  in process titles, which allows to monitor the success of configuration
  reloads and the number of previous worker process generations using the
  `ps` utility.
- All functionality of [nginx 1.25.2](https://nginx.org/en/CHANGES).



#### Changes

- Now appname `angie` is used
  when loading the OpenSSL configuration.

#### Packages

- Updated:
  - [angie-pro-module-njs](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs), to version 0.8.1

---



### Angie PRO 1.2.0

Release date: 15.08.2023.

#### Features

- [HTTP RESTful JSON interface](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-config) for reconfiguring, adding, or
  deleting servers in the HTTP [Upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream) module's
  [upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) blocks, and the [state](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-state) directive
  for persisting these changes.
- The [upstream_probe (PRO)](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe) directive to check the health of servers in the
  HTTP [Upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream) module's [upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) block by
  periodically sending probe requests.
- Support for cache sharding in the HTTP [Proxy](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy) module, which
  enables caching responses in different directories (drives) depending on an
  arbitrary response parameter, configured with variables in the new
  `path=` option of the [proxy_cache](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache) directive.
- Support for NTLS in the HTTP [SSL](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#http-ssl) and Stream
  [SSL](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#stream-ssl) modules when using the [TongSuo](https://github.com/Tongsuo-Project/Tongsuo) TLS library; the support can
  be enabled via the `‑‑with‑ntls` build time option and configured
  with the corresponding [ssl_ntls](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-ntls) and [proxy_ssl_ntls](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ssl-ntls) directives.
- In the HTTP [Proxy](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy) and Stream [Proxy](https://en.angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#stream-proxy)
  modules, the ability to specify multiple certificates with different types
  (RSA and ECDSA) and corresponding keys using the [proxy_ssl_certificate](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ssl-certificate)
  and [proxy_ssl_certificate_key](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ssl-certificate-key) directives.
- Display of version and build name in the `master` process title, which
  allows to get this information about a running server instance using the
  `ps` utility.
- The [GZip](https://en.angie.software//angie/docs/configuration/modules/http/http_gzip.md#http-gzip) module's ability to compress "207 Multi-Status"
  responses.  Thanks to [DBotThePony](https://github.com/webserver-llc/angie/pull/26).
- All functionality of [nginx 1.25.0](https://nginx.org/en/CHANGES),
  including [HTTP/3](https://en.angie.software//angie/docs/configuration/modules/http/http_v3.md#http-v3) support.



#### Changes

- The [$upstream_sticky_status](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-sticky-status) variable values are now uppercase to be in
  line with the style of [$upstream_cache_status](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-cache-status) values.

#### Packages

- Dynamic modules added:
  - [angie-pro-module-enhanced-memcached](https://en.angie.software//angie/docs/configuration/modules/external-modules/enhanced-memcached.md#external-enhanced-memcached)
  - [angie-pro-module-eval](https://en.angie.software//angie/docs/configuration/modules/external-modules/eval.md#external-eval)

---



### Angie PRO 1.1.0-p1

Release date: 01.03.2023.

#### Features

- The [sticky](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky) directive and related options in the HTTP
  [Upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream) module's [upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) block that allow to
  configure sticky sessions mode, where all requests of the session are routed
  to the same server.
- The [$upstream_sticky_status](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-sticky-status) variable that can be either `new`,
  `hit` or `miss` depending on the success of requesting the related
  upstream server with sticky sessions enabled.

---



### Angie PRO 1.1.0

Release date: 07.02.2023.

#### Features

- The [api](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#a-api) directive that provides HTTP RESTful interface for accessing
  in JSON or Prometheus formats basic information about a web server instance,
  as well as [metrics](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#metrics) of client connections, shared memory
  zones, DNS queries, HTTP requests, HTTP responses cache, TCP/UDP sessions of
  [Stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) module, zones of
  [Limit Conn](https://en.angie.software//angie/docs/configuration/modules/http/http_limit_conn.md#http-limit-conn)/[Limit Req](https://en.angie.software//angie/docs/configuration/modules/http/http_limit_req.md#http-limit-req) modules,
  and groups of [HTTP upstream servers](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream).
- The [resolve](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve) option of the [server](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server)
  directive in the HTTP [Upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream) module's
  [upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) block that allows to monitor changes to the list of IP
  addresses corresponding to a domain name, and automatically update it without
  the need of reloading configuration.
- The [service](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve) option of the [server](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server)
  directive in the HTTP [Upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream) module's
  [upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) block that allows to retrieve lists of addresses from DNS
  SRV records, with basic priority support.
- The [status_zone](https://en.angie.software//angie/docs/configuration/modules/http/index.md#status-zone) directive in [HTTP](https://en.angie.software//angie/docs/configuration/modules/http/index.md#http-core)
  module for specifying zone to collect request metrics in [server](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server) and
  [location](https://en.angie.software//angie/docs/configuration/modules/http/index.md#location) contexts.
- The [status_zone](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#s-status-zone) directive in [Stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) module for specifying zone to collect TCP/UDP session metrics.
- The [status_zone](https://en.angie.software//angie/docs/configuration/modules/http/index.md#resolver-status) parameter of the [resolver](https://en.angie.software//angie/docs/configuration/modules/http/index.md#resolver)
  directive for specifying zone to collect metrics on DNS queries.
- [autoindex](https://en.angie.software//angie/docs/configuration/modules/http/http_autoindex.md#id1) uses natural sorting order for directory listings.
- Arbitrary configuration of the signature on default error pages and the
  `Server` response header field via the [server_tokens](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server-tokens) directive.
- The [$angie_version](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-angie-version) variable with version of Angie.
- All functionality of [nginx 1.23.3](https://nginx.org/en/CHANGES).

#### Packages

07.04.2023

- Added packages for [ALT](https://en.angie.software//angie/docs/installation/pro_packages.md#install-alt-pro) Linux.

12.05.2023

- Added packages for [FreeBSD](https://en.angie.software//angie/docs/installation/pro_packages.md#install-freebsd-pro).
- Dynamic modules added:
  - [angie-pro-module-subs](https://en.angie.software//angie/docs/configuration/modules/external-modules/subs.md#external-subs)
  - [angie-pro-module-upload](https://en.angie.software//angie/docs/configuration/modules/external-modules/upload.md#external-upload)
  - [angie-pro-module-vod](https://en.angie.software//angie/docs/configuration/modules/external-modules/vod.md#external-vod)

26.05.2023

- Added packages for [Astra](https://en.angie.software//angie/docs/installation/pro_packages.md#install-astrase-pro) Linux Special Edition.

13.06.2023

- Added packages for [Debian 12 "Bookworm"](https://en.angie.software//angie/docs/installation/pro_packages.md#install-deb-pro) and
  [AlmaLinux](https://en.angie.software//angie/docs/installation/pro_packages.md#install-yum-pro).

12.07.2023

- Dynamic modules added:
  - [angie-pro-module-cache-purge](https://en.angie.software//angie/docs/configuration/modules/external-modules/cache-purge.md#external-cache-purge)
  - [angie-pro-module-echo](https://en.angie.software//angie/docs/configuration/modules/external-modules/echo.md#external-echo)
  - [angie-pro-module-keyval](https://en.angie.software//angie/docs/configuration/modules/external-modules/keyval.md#external-keyval)
  - [angie-pro-module-postgres](https://en.angie.software//angie/docs/configuration/modules/external-modules/postgres.md#external-postgres)
- Updated:
  - [angie-pro-module-njs](https://en.angie.software//angie/docs/configuration/modules/external-modules/njs.md#external-njs), to version 0.8.0

31.07.2023

- Dynamic modules added:
  - [angie-pro-module-auth-jwt](https://en.angie.software//angie/docs/configuration/modules/external-modules/auth-jwt.md#external-auth-jwt)