# https://en.angie.software/index.md
# Welcome!
[News](https://en.angie.software/news/)
* [Angie and Angie PRO updated to version 1.11.8](https://en.angie.software/news/releases/angie-1-11-8/) - Maintenance releases of Angie and Angie PRO 1.11.8 fix several vulnerabilities found in nginx and an error in handling the acme_http_port and acme_dns_port directives. (18.06.2026)
* [Angie and Angie PRO updated to version 1.11.7](https://en.angie.software/news/releases/angie-1-11-7/) - Maintenance releases of Angie and Angie PRO 1.11.7 have been published, fixing issues in the ACME, Docker, and Metric modules and adding compatibility with OpenSSL 4.0. (15.06.2026)
* [Angie and Angie PRO updated to version 1.11.6](https://en.angie.software/news/releases/angie-1-11-6/) - A maintenance release of Angie and Angie PRO 1.11.6 has been published, porting a fix for the CVE-2026-9256 vulnerability in the rewrite directive, discovered in nginx the day before. (25.05.2026)
Angie Software (Web Server, LLC) is a Russian IT company that develops
solutions for high-load systems.
Among our products are: the load balancing system
[Angie ADC](https://en.angie.software//adc/index.md) (Application Delivery Controller), the web server
[Angie PRO](https://en.angie.software//angie/pro/index.md), and [Angie Ingress Controller (ANIC)](https://en.angie.software//anic/index.md) — a solution
for managing traffic of containerized applications in Kubernetes.
Our
special pride is [the open-source web server Angie](https://en.angie.software//angie/index.md), which was created as a fork of
nginx and aims to surpass the functionality of the original.
## Why choose our solutions?
The core of our team comprises specialists who were at the origins of
the once globally recognized leader in the web server and load balancing market —
NGINX, and also held leading engineering positions at F5 Networks.
We regularly give presentations at international industry
conferences and possess unique competencies, being the main
developers of the nginx web server since 2011.
Our products are based on nginx technologies, which have proven themselves
with security, fault tolerance, and
scalability under high loads. Backward compatibility allows you to
operate our solutions without additional costs for implementation and
staff retraining. As the original authors and developers,
we thoroughly understand our products and can solve the most complex
tasks.
In addition to commercial products with extended functionality, we
develop open-source products whose quality
is at a global level. Our Angie project under the free BSD
license is a further development of nginx and aims to surpass its
capabilities and fully replace it. A cohesive community has
already formed around Angie, and the regularity of releases with new features and high
quality standards attract more and more users from all over the world.
Our team's engineers have provided support to the largest companies
around the world, including those in the Fortune 500 list. They have been
repeatedly awarded prestigious international awards for their work, such as
the Silver Stevie Winner for Sales and Customer Service 2016 and the Gold
Stevie Winner for Sales and Customer Service 2017.
# https://en.angie.software/404.md
# Page Not Found
It could be moved or deleted, or there may be a typo in the URL.
Go back to the [home page](/) and start over,
try a [short link](https://angie.ws/en/),
or use the [search](/search/).
If you believe this is a mistake,
contact us on the [community forum](https://forum.angie.support/)
or in the [Telegram channel](https://t.me/angie_support).
# https://en.angie.software/500.md
# Server Error
An unexpected error occurred on the server. Please wait; it will be fixed soon.
[Return to Home](https://en.angie.software//index.md)
# https://en.angie.software/vacancies/UX-UI-designer.md
# UX/UI Designer (Angie ADC)
We are the team behind Angie Software. The core of the company is a group of experienced developers who stood at the origins of nginx and are now building its evolutionary successor — Angie. Our products are already gaining traction worldwide, and we have set ourselves an ambitious goal: to outpace market giants like F5, Citrix, and Radware.
Angie ADC is a modern, enterprise-grade application delivery controller. It handles traffic routing, load balancing, SSL offloading, and security — everything needed to keep applications running smoothly inside complex network infrastructures. We are convinced that the key to winning lies not only in the technical excellence of the engine, but also in a deep understanding of market needs that turns complex things into a product people actually want.
Our culture is informal and flat: we talk to each other as equals, without bureaucracy or unnecessary formalities. Decisions are made quickly, and arguments matter more than job titles.
## What you will be doing:
- Rethinking and evolving the UX/UI of Angie ADC end-to-end, turning complex networking concepts (load balancing, topologies, security policies) into intuitive and beautiful interfaces for engineers;
- Designing user flows, building prototypes and detailed mockups, shaping UI components, icons, and guidelines that together form the product's visual language;
- Running usability tests, audience research, and feedback analysis to validate hypotheses and continuously improve the experience based on data rather than guesswork;
- Working hand in hand with the development team and the technical product manager: finding the right balance between technical feasibility, business value, and an excellent user experience.
## Who we are looking for:
- Believes that UX is a strategy and a competitive advantage, not just "pretty buttons";
- Has at least 3 years of UX/UI experience and has worked on complex infrastructure or enterprise products;
- Has systems thinking and can break down a technically complex domain into clear patterns and scenarios, rather than just following trends;
- Is confident with Figma and other tools, but even more confident with user research methods and data analysis, so they can justify their decisions in front of any audience;
- Has a technical background or enough curiosity to dive quickly into networking nuances and speak the same language as developers;
- Wants to build a product used by engineers at leading companies.
## What we offer:
- A real opportunity to influence a world-class product and see your decisions come to life without the inertia of large corporations;
- Work in a team of recognized industry experts, where expertise, initiative, and ownership are valued;
- A flat structure in which your voice truly matters and bureaucracy simply does not exist;
- A competitive salary, private medical insurance, paid training and conferences — we are invested in your professional growth;
- An accredited IT company and transparent terms.
**Work format:** hybrid or full-time office (open for discussion), Savyolovskaya metro station, Factoria business center.
If you're interested, send your resume to [hr@wbsrv.ru](mailto:hr@wbsrv.ru).
# 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.
- **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.
```
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
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/installation/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/|angie_version|
Date: |sampledatelong| 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
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/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/installation/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
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/company.md
# About Us
We are a Russian IT company engaged in software development.
Our company, founded by former NGINX employees, has developed Angie —
a high-performance and scalable web server, created as a fork of nginx
and designed to surpass the functionality of the original, becoming a sought-after
web server in the market for cluster software solutions.
We are currently actively developing a range of solutions based on Angie,
adding new features in accordance with market demands.
Our products:
- Angie and its commercial version Angie PRO. They significantly improve
fault tolerance, performance, and operating conditions compared to
nginx, and the specialists from the [technical support](https://en.angie.software//service.md)
of the "Web Server" company will assist in setting up uninterrupted operation
for both Angie-based solutions and nginx.
- Angie Ingress Controller (ANIC). A solution for managing
traffic of containerized applications in Kubernetes.
ANIC is based on the capabilities of Angie PRO, allowing the construction of secure,
scalable, high-performance environments using a Russian solution
with professional migration services and technical support in Russian.
- The Angie Application Delivery Controller (Angie ADC) is currently in development.
It is a boxed solution in the "load balancing systems" class in the form of a virtual appliance
(and in the future a hardware-software solution), addressing the diverse mosaic
of corporate requests in the Russian market in this area.
Angie PRO, ANIC, and Angie ADC are included in the Unified Register of Russian Software
for electronic computing machines and databases. The company's products undergo
compatibility testing with domestic systems Astra Linux, Alt, RED OS, and ROSA.
Our services:
- [standard technical support](https://en.angie.software//support/index.md);
- [corporate technical support](https://en.angie.software//support/enterprise.md);
- highly qualified [professional services](https://en.angie.software//professional-service.md)
for migration, adaptation, and optimization of our
products in clients' infrastructures.
Together with our partners, we develop training courses and certification programs
for working with our products.
Media coverage about us:
- [Kommersant, nginx is being rebuilt in Russia.](https://www.kommersant.ru/doc/5634072)
- [Vedomosti, The first Russian web server has been included in the register of domestic software.](https://www.vedomosti.ru/technology/articles/2023/05/24/976527-pervii-rossiiskii-veb-server-vnesen-v-reestr-otechestvennogo-po?shared_token=cbe20f6feeee8a5bcf52f077d2d6ad62b66e3917)
- [Habr, "Web Server" presented ANIC — software for traffic management in the Kubernetes network.](https://habr.com/news/744654/)
- [Marketplace for developers: how to develop the Russian GitHub.](https://www.forbes.ru/mneniya/491830-marketplejs-dla-razrabotcikov-kak-razvivat-rossijskij-github)
- [Closed zones of open code: how China and Russia are developing open source.](https://www.forbes.ru/tekhnologii/495635-zakrytye-zony-otkrytogo-koda-kak-kitaj-i-rossia-razvivaut-open-source)
- [Interview with our lead developer Valentin Bartenev on Habr.](https://habr.com/articles/774274/)
- [Valentin Bartenev's talk at HighLoad (on YouTube).](https://www.youtube.com/watch?v=CKHNqMawUiE)
# 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`, `16g`.
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";
```
## 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.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)
## 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).
## 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)
# https://en.angie.software/news/releases/console-light-1-6-0.md
# Angie Console Light updated to version 1.6.0
*23.01.2025*
Angie Console Light, the visual console which helps monitor web server metrics
in real time, including performance and load, has been updated to version 1.6.0.
Angie Console Light, the visual console which helps monitor web server metrics in real time,
including performance and load, has been updated to version 1.6.0.
The new version of the console includes:
- Internationalisation (i18n), available locales: en, ru;
- Sticky headers for tables;
- Support for the pebibyte (PiB) data measurement unit.
Additionally, an incorrect value counter in the "HTTP Upstreams" widget on the index page has been fixed.
Now, when no data is available in the response context, a default value is used.
With Angie Console Light, you can monitor metrics for a specific web server instance.
Administrators can configure the data refresh interval on the page.
The console is available as the package `angie-console-light` [in the Angie Software repositories](https://github.com/webserver-llc/angie-console-light/releases/tag/1.6.0),
and you can explore the demo version of Console Light at
[https://console.angie.software/](https://console.angie.software/).
Previously, we described [in a separate article](https://habr.com/en/articles/763626/) how to set up Angie monitoring,
including the capabilities of Console Light.
# https://en.angie.software/contacts.md
# Contacts
Phone: +7 (495) 120 50 33
Email: [info@wbsrv.ru](mailto:info@wbsrv.ru)
Address: 127015, Moscow, Vyatskaya St., 27, bld. 7
[Support on Telegram](https://t.me/angie_support) (RU, EN)
[News on Telegram](https://t.me/angie_software) (RU)
# https://en.angie.software/angie/contributor-agreement.md
# Contributor License Agreement
This Agreement governs the relationship between the Company and the
Contributor, in which the parties assume the rights and obligations set forth
in the text of the license agreement with the Contributor, hereinafter referred
to as the Agreement:
**Terms and definitions**:
**Contributions** are the results of intellectual activity (including, but not
limited to, source code, design entities, text, and documentation) that are
elements of the Programs.
**Programs** are the software (computer programs) to which
the Company has exclusive rights, as well as all new (subsequent) versions of
such programs.
**Contributor** is, (1) if the Contribution is made by an individual on his or
her own behalf, an individual with the requisite legal capacity who has
accepted all of the terms of this Agreement; (2) if the Contribution is made by
an individual on behalf of a legal entity or individual entrepreneur as its employer, the applicable legal entity or individual entrepreneur.
**Company** is Web Server, LLC, a legal entity registered under the laws of the
Russian Federation (OGRN: 1227700436578) at the following address: Moscow, 127015, Vyatskaya St., 27, bld. 7.
**Party** is one of the parties to the Agreement: the Contributor or
the Company.
1. The subject matter of this Agreement is that the Contributor grants to the
Company the right to use the Contributions on the terms of a non-exclusive,
royalty-free, irrevocable license, including all means expressly provided
for and specified in this Agreement.
The license is granted for the entire duration of the exclusive right to the
Contributions, and the permitted territory is all countries in the world.
Contributions may be provided (transferred) by the Contributor to the Company
in any manner (on a tangible medium, in electronic form via email, in the form
of a change request, or using the contribution transfer systems used on
GitHub, GitLab, or other similar sites). Contributions shall be deemed provided
on the date the Company receives them.
As of the date of actual provision of the Contributions to the Company, the
Contributor expresses full and unconditional agreement with all of the terms
of this Agreement.
2. **Use of Contributions by the Company**. The Company shall have the right to use
the Contributions in the following ways:
2.1. use the Contributions for both commercial and non-commercial purposes in
any Programs (both open and closed source); use the Contributions in any other
results of intellectual activity, the rights to which belong to the Company;
2.2. make any changes, abridgements and additions to the Contributions, add
comments, images or explanations to the Contributions when using them;
2.3. create any other (derivative) results of intellectual activity based on
the Contributions;
2.4. translate the Contributions into other languages, including other
programming languages;
2.5. distribute the Contributions in any way, including making the
Contributions available to any third party, both directly and as part of any
Programs, on an "AS IS" basis, without the need to provide any warranties as to their operability/freedom from defects and errors;
2.6. conduct public displays, make the Contributions available to the general public;
2.7. disassemble, decompile (convert object code into source code), perform
engineering analysis of the Contributions.
2.8. use the Contributions without mentioning the author's name and/or
pseudonym (anonymously).
3. The Contributor grants the Company a non-exclusive, royalty-free, perpetual,
irrevocable license to the Contributor's patent rights in the territory of
all countries in the world. This license includes all patent rights held by
the Contributor.
4. **Representations**. The Contributor provides the Company with the
following representations as to matters the Company deems material to the
execution and conclusion of the Agreement by the Company:
4.1. the Contributor has all the rights necessary to enter into the Agreement;
4.2. the Contributions provided by the Contributor to the Company have been
personally developed by the Contributor, with the exception of Contributions,
the exclusive rights to which are owned by other persons (rights holders), but
which, with the consent of such rights holders, are distributed without the
need for coordination with the rights holders and without payment of remuneration to them, and
the Contributor uses such Contributions on legal grounds;
4.3. the Contributions are not encumbered by any third party rights;
4.4. the Contributor has obtained the consent of the owners of the intellectual
property rights included in the Contributions (if any) for their use by the
Company in all ways specified in the Agreement;
4.5. the Company's further use of the Contributions in the form in which they
are transferred by the Contributor to the Company does not infringe any third
party intellectual property rights or any other legitimate interests and rights of third parties.
5. **Liability**. If the Company faces any claims or
lawsuits relating to the use of the Contributor's Contributions, the
Contributor agrees to compensate all losses of the Company
that may arise as a result of such claims or lawsuits.
6. **Limitation of Liability**. All Contributions provided by the Contributor to
the Company are provided on an "AS IS" basis without any warranties whatsoever.
7. **Trademarks**. The Contributor may use the Company's logo and trademarks
only with the prior written consent of the Company. To obtain written consent,
the Contributor must send a letter to the Company's email address: [legal@wbsrv.ru](mailto:legal@wbsrv.ru).
8. **Dispute Resolution and Applicable Law**. The Agreement shall be governed by
and construed in accordance with the laws of the Russian Federation. If the
Parties do not agree on the disputed issues, the dispute shall be subject to
consideration by the court at the Company's location, unless the law
directly provides otherwise.
9. The Company is under no obligation to provide the Contributor with
reports on the use of the Contributions.
10. **Agreement Language**. This Agreement is written in Russian and English
languages.
The Russian version of the Agreement is available at:
[https://angie.software/angie/contributor-agreement/](https://angie.software/angie/contributor-agreement/)
The English version of the Agreement is available at:
[https://en.angie.software/angie/contributor-agreement/](https://en.angie.software/angie/contributor-agreement/)
In case of any discrepancy between the Russian-language and the
English-language versions of the Agreement, the Russian-language provisions
shall prevail.
11. **Entry into Force of the Agreement**. This Agreement shall be deemed to be in effect and
concluded between the Parties upon receipt by the Company of the
Contribution from the Contributor in any form and by any means referred to
in Section 1 of the Agreement. This includes, but is not limited to,
receiving the Contribution to the Company's corporate accounts on the
GitHub and/or GitLab websites.
Web Server, LLC.
OGRN: 1227700436578.
Address: Moscow, 127015, Vyatskaya St., 27, bldg. 7.
Tel.: +7 (495) 120 50 33.
Email: [legal@wbsrv.ru](mailto:legal@wbsrv.ru).
Publication date: 08.11.2023.
# 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; |
|------------------------------------------------------------------------------------------|------------------------------|
| 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
| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `error_log` file [level] [[`filter=`type:value] ...]; |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 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=` parameters restrict which messages are written to the log.
Supported filters are:
- `filter=file:`prefix matches a source file prefix (for example,
`ngx_http_access_module.c`);
- `filter=event:`prefix matches an event ID prefix (for example,
`http.upstream.peer`);
- `filter=tag:`tag matches a tag attached to the log entry.
Multiple `filter=file:` or `filter=event:` parameters are matched
by prefix, and any match allows the message to pass. Multiple
`filter=tag:` parameters require all tags to be present.
Tags can be added automatically by modules (for example,
`http`, `stream`, `mail`, `upstream`,
`peer`, `subrequest`) and by
[error_log_user_tag](https://en.angie.software//angie/docs/configuration/modules/http/index.md#error-log-user-tag) directives.
#### 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.
Each entry in the error log has the following format:
```text
timestamp [level] PID#TID: *request_id message
```
Where:
- `timestamp` — date and time of the event
- `level` — logging level of the event
- `PID#TID` — process and thread identifiers
- `*request_id` — unique request identifier (if applicable)
- `message` — error or event message text
### 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; |
|------------------------------------------------------------------------------------------|------------------------------|
| 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; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| Default | — |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | main |
Configures a timeout in seconds 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/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.
## 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#id3) directive.
Use a `key=value` pair (both are [complex values](https://en.angie.software//angie/docs/configuration/configfile.md#syntax)), 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/installation/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/|angie_version|
Date: |sampledatelong| 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/|angie_version|
Date: |sampledatelong| 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/|angie_version|
Date: |sampledatelong| 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/|angie_version|
Date: |sampledatelong| 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/|angie_version|
Date: |sampledatelong| 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/|angie_version|
Date: |sampledatelong| 19:15:35 GMT
Connection: keep-alive
```
The file has been successfully unlocked and overwritten.
## Additional Information
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/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#syntax) 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#syntax) 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#syntax) 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#syntax) 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#syntax) 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 [core HTTP module](https://en.angie.software//angie/docs/configuration/modules/http/index.md#http-core)
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 Module](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/installation/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/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/doc-license.md
# Notice of Presence of Licensed Components
[Documentation](https://en.angie.software//angie/docs/index.md) for Angie software product, as published on this site, is the
intellectual property of Web Server, LLC; the documentation was created as a
result of modification (revision) of documentation for Nginx software product.
Certain portions of the Angie software product documentation that were used
unchanged are licensed under the license available at [http://nginx.org/LICENSE](http://nginx.org/LICENSE);
use of such portions of the documentation is permitted only in accordance with
the terms of this license.
# 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 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 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 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/|version|
Date: |sampledatelong| 10:42:54 GMT
Content-Type: text/html
Content-Length: 543
Last-Modified: |sampledatelong| 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.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 |nginxversion|](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 |angie_version|** and **Angie PRO |angie_pro_version|** were released on **|angie_release_date|**.
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).
## Features
Core advantages over nginx,
available in the free open-source version of Angie:
- Supporting [HTTP/3](https://en.angie.software//angie/docs/configuration/modules/http/http_v3.md#http-v3) for client connections,
as well as for [proxied server](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http-version) connections,
with the ability to independently use different protocol versions
(HTTP/1.x, HTTP/2, HTTP/3)
on opposite sides.
- Automatic HTTPS provisions TLS certificates using built-in [ACME](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#id1) protocol support.
- Simplifying configuration: the `location` directive
can define several matching expressions at once, which enables
[combining](https://en.angie.software//angie/docs/configuration/modules/http/index.md#combined-locations) blocks with shared settings.
- 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, 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.
- 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).
- 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/)
- 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.
- 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
preserves the cache index contents between restarts and updates,
which eliminates the cache load delay and brings the server online even faster.
- [Session binding](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky) mode, which directs all requests
within one session to the same proxied server.
- 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.
- 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.
- 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`.
- [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).
- Pre-built [binary packages](https://en.angie.software//angie/docs/installation/external-modules/index.md#install-thirdpartymodules)
for many popular third-party modules.
---
Commercial Angie PRO adds the following
to the [publicly available features](#index-features-oss):
- Managing of proxied servers
through a RESTful dynamic configuration
[API](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-config);
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.
- 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).
- Load balancing based on [average response time](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-least-time)
from proxied servers with [customizable smoothing factor](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-response-time-factor).
- [Feedback-based](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-feedback) load balancing
that selects peers based on a variable value;
supposedly, it comes from the peers themselves,
reporting their 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.
- Additional binding mode [sticky learn](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky),
enabling detection and storage of client sessions in shared memory
or external storage, which allows joining multiple balancers in a cluster.
- Using the [backup_switch](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 backup servers
to continue serving requests when the primary servers become accessible again.
- 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.
- Cache sharding in the proxy module, which enables distributing it between
[locations](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache) depending on the properties of the response.
- Server signature on error pages and in the `Server` header field
can be hidden or overridden with the [server_tokens](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server-tokens) directive.
# https://en.angie.software/angie/docs/installation/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
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/installation/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
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/installation/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
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/support/enterprise.md
# Corporate Technical Support
Corporate technical support provides a high level of service for critical infrastructure components. Corporate technical support services include all the capabilities of standard technical support, as well as:
- guaranteed initial response time – up to 2 hours;
- 24/7 support.
Full terms of service can be found [`here`](https://en.angie.software//support/Angie_enterprise.pdf).
## Comparison of Standard and Corporate Technical Support Terms
| | Standard | Corporate |
|----------------------------------------------------------|------------|-------------|
| Provided based on a separate technical support agreement | | |
| Support requests via email and online form | | |
| Support requests via phone | | |
| Support hours: weekdays from 10 AM to 8 PM, Moscow time | | |
| Support hours: 24/7 | | |
| Initial response time to requests: up to 2 hours | | |
## Services Provided Under Corporate Technical Support
- Troubleshooting software functionality issues.
- Consulting on software usage and providing clarifications on documentation.
- Consulting on the operation of HTTP and TCP protocols during software operation.
- Consulting on modifying user operating system settings to improve software performance.
- Consulting on optimization opportunities for software interaction with other solutions installed by the user.
- Providing support for customizing configuration files to meet individual user requests.
- Providing updates during the term of technical support services.
# https://en.angie.software/legal/eula.md
# End-User License Agreement
#### NOTE
The legally binding End-User License Agreement is published in
Russian. The Russian original is the authoritative version; this page
provides an English-language reference. Please consult the Russian
original or contact [info@wbsrv.ru](mailto:info@wbsrv.ru) for assistance.
The current End-User License Agreement (EULA) governs the use of Angie
Software products distributed by Web Server, LLC (the Rights Holder)
either directly to End Users or via the Rights Holder's Partners,
including as part of integrated hardware-software solutions.
To review the current and previous versions of the EULA, refer to the
Russian-language source on the Angie website.
# https://en.angie.software/angie/docs/installation/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
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/news/events.md
# Events
## [Web Server Angie a Year Later: New Opportunities and Future Plans](https://en.angie.software//news/events/veb-server-angie-god-spustya-novie-vozmozhnosti.md)
*27.11.2023*
Valentin Bartenyev, head of development for Angie, will discuss the first year of our project at HighLoad 2023.
# https://en.angie.software/angie/docs/installation/external-modules.md
# 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 Modules
| Module | Version | Packages | Description |
|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------|--------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Auth JWT](https://en.angie.software//angie/docs/installation/external-modules/auth-jwt.md#external-auth-jwt) | 0.9.0 | `angie-module-auth-jwt` `angie-pro-module-auth-jwt` | Adds JWT authentication for clients. |
| [Auth LDAP](https://en.angie.software//angie/docs/installation/external-modules/auth-ldap.md#external-ldap) | 241200e | `angie-module-auth-ldap` `angie-pro-module-auth-ldap` | Adds support for LDAP authentication with multiple servers. |
| [Auth PAM](https://en.angie.software//angie/docs/installation/external-modules/auth-pam.md#external-auth-pam) | v1.5.5 | `angie-module-auth-pam` `angie-pro-module-auth-pam` | Adds support for PAM authentication. |
| [Auth SPNEGO](https://en.angie.software//angie/docs/installation/external-modules/auth-spnego.md#external-auth-spnego) | v1.1.3 | `angie-module-auth-spnego` `angie-pro-module-auth-spnego` | Adds support for SPNEGO and GSSAPI. |
| [Auth TOTP](https://en.angie.software//angie/docs/installation/external-modules/auth-totp.md#external-auth-totp) | 1.1.0 | `angie-module-auth-totp` `angie-pro-module-auth-totp` | Adds TOTP-based one-time password authentication. |
| [Brotli](https://en.angie.software//angie/docs/installation/external-modules/brotli.md#external-brotli) | v1.0.0rc | `angie-module-brotli` `angie-pro-module-brotli` | Adds static and dynamic Brotli compression for responses. |
| [Cache Purge](https://en.angie.software//angie/docs/installation/external-modules/cache-purge.md#external-cache-purge) | 2.5.3 | `angie-module-cache-purge` `angie-pro-module-cache-purge` | Allows purging content from FastCGI, proxy, SCGI, and uWSGI caches. |
| [CGI](https://en.angie.software//angie/docs/installation/external-modules/cgi.md#external-cgi) | v0.13 | `angie-module-cgi` `angie-pro-module-cgi` | Adds support for CGI. |
| [Combined Upstreams](https://en.angie.software//angie/docs/installation/external-modules/combined-upstreams.md#external-combined-upstreams) | 2.3.1 | `angie-module-combined-upstreams` `angie-pro-module-combined-upstreams` | Allows combining multiple server groups into one. |
| [DAV Ext](https://en.angie.software//angie/docs/installation/external-modules/dav-ext.md#external-dav-ext) | v3.0.0 | `angie-module-dav-ext` `angie-pro-module-dav-ext` | Extends WebDAV support with PROPFIND and OPTIONS methods. |
| [Dynamic Limit Req](https://en.angie.software//angie/docs/installation/external-modules/dynamic-limit-req.md#external-dynamic-limit-req) | 1.9.3 | `angie-module-dynamic-limit-req` `angie-pro-module-dynamic-limit-req` | Serves to dynamically block IP addresses and periodically unblock them. |
| [Echo](https://en.angie.software//angie/docs/installation/external-modules/echo.md#external-echo) | v0.63 | `angie-module-echo` `angie-pro-module-echo` | Allows calling `echo`, `sleep`, `time`, `exec` and other shell commands in the configuration file. |
| [Enhanced Memcached](https://en.angie.software//angie/docs/installation/external-modules/enhanced-memcached.md#external-enhanced-memcached) | v0.3 | `angie-module-enhanced-memcached` `angie-pro-module-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/installation/external-modules/eval.md#external-eval) | 2016.06.10 | `angie-module-eval` `angie-pro-module-eval` | Allows saving response bodies of subrequests into variables. |
| [GeoIP2](https://en.angie.software//angie/docs/installation/external-modules/geoip2.md#external-geoip2) | 3.4 | `angie-module-geoip2` `angie-pro-module-geoip2` | Adds geolocation search in MaxMind GeoIP2 databases. |
| [Headers More](https://en.angie.software//angie/docs/installation/external-modules/headers-more.md#external-headers-more) | v0.39 | `angie-module-headers-more` `angie-pro-module-headers-more` | Allows setting and clearing request and response headers. |
| [HTTP Auth Radius](https://en.angie.software//angie/docs/installation/external-modules/http-auth-radius.md#external-http-auth-radius) | 458af16 | `angie-module-http-auth-radius` `angie-pro-module-http-auth-radius` | Adds support for Radius. |
| [JWT](https://en.angie.software//angie/docs/installation/external-modules/jwt.md#external-jwt) | v3.4.3 | `angie-module-jwt` `angie-pro-module-jwt` | Lightweight alternative to [Auth JWT](https://en.angie.software//angie/docs/installation/external-modules/auth-jwt.md#external-auth-jwt). |
| [Keyval](https://en.angie.software//angie/docs/installation/external-modules/keyval.md#external-keyval) | 0.3.0 | `angie-module-keyval` `angie-pro-module-keyval` | Allows using variables with values from key-value pairs. |
| [Lua](https://en.angie.software//angie/docs/installation/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.28 / v0.0.16 | `angie-module-lua` `angie-pro-module-lua` | Allow using the Lua language in Angie configuration in the `http` and `stream` contexts, respectively. |
| [ModSecurity](https://en.angie.software//angie/docs/installation/external-modules/modsecurity.md#external-modsec) | v1.0.4 | `angie-module-modsecurity` `angie-pro-module-modsecurity` | Adds a connector for using ModSecurity rules. |
| [NJS](https://en.angie.software//angie/docs/installation/external-modules/njs.md#external-njs): [http_js](https://en.angie.software//angie/docs/installation/external-modules/http_js.md#http-js), [stream_js](https://en.angie.software//angie/docs/installation/external-modules/stream_js.md#stream-js) | 0.9.1 | `angie-module-njs` `angie-pro-module-njs` | 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/installation/external-modules/ndk.md#external-ndk) | v0.3.4 | `angie-module-ndk` `angie-pro-module-ndk` | Adds the Nginx Development Kit (NDK) for developing new modules. |
| [OpenTracing](https://en.angie.software//angie/docs/installation/external-modules/opentracing.md#external-opentracing) | v0.41.0 | `angie-module-opentracing` `angie-pro-module-opentracing` | Adds distributed OpenTracing request tracing in Angie; contains plugins for exporting data to Zipkin and DataDog. |
| [OpenTelemetry](https://en.angie.software//angie/docs/installation/external-modules/otel.md#external-otel) | v0.1.2 | `angie-module-otel` `angie-pro-module-otel` | Allows sending telemetry data to the OpenTelemetry collector. |
| [PostgreSQL](https://en.angie.software//angie/docs/installation/external-modules/postgres.md#external-postgres) | 1.0rc7 | `angie-module-postgres` `angie-pro-module-postgres` | Includes direct support for PostgreSQL databases. |
| [Redis2](https://en.angie.software//angie/docs/installation/external-modules/redis2.md#external-redis2) | v0.15 | `angie-module-redis2` `angie-pro-module-redis2` | Includes support for Redis 2.0 for HTTP upstreams. |
| [RTMP](https://en.angie.software//angie/docs/installation/external-modules/rtmp.md#external-rtmp) | v1.2.2 | `angie-module-rtmp` `angie-pro-module-rtmp` | Includes support for RTMP for streaming and video-on-demand broadcasts. |
| [Set Misc](https://en.angie.software//angie/docs/installation/external-modules/set-misc.md#external-set-misc) | v0.33 | `angie-module-set-misc` `angie-pro-module-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/installation/external-modules/subs.md#external-subs) | e12e965 | `angie-module-subs` `angie-pro-module-subs` | Allows replacing strings in HTTP response bodies using regular expressions. |
| [TestCookie](https://en.angie.software//angie/docs/installation/external-modules/testcookie.md#external-testcookie) | 64137c2 | `angie-module-testcookie` `angie-pro-module-testcookie` | Helps combat bots using a "challenge-response" mechanism based on cookies. |
| [UnBrotli](https://en.angie.software//angie/docs/installation/external-modules/unbrotli.md#external-unbrotli) | 60bed63 | `angie-module-unbrotli` `angie-pro-module-unbrotli` | Unpacks responses with `Content-Encoding: br` for clients that do not support Brotli encoding. |
| [Upload](https://en.angie.software//angie/docs/installation/external-modules/upload.md#external-upload) | 2.3.0 | `angie-module-upload` `angie-pro-module-upload` | Adds `multipart/form-data` (RFC 1867) encoding for file uploads from the client, including resume capability. |
| [VOD](https://en.angie.software//angie/docs/installation/external-modules/vod.md#external-vod) | 1.33 | `angie-module-vod` `angie-pro-module-vod` | Allows repackaging MP4 files for streaming via HLS, HDS, MSS, and DASH. |
| [VTS](https://en.angie.software//angie/docs/installation/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.4 / v0.1.1 / v0.1.1 | `angie-module-vts` `angie-pro-module-vts` | Include the three listed modules for traffic monitoring. |
| [ZIP](https://en.angie.software//angie/docs/installation/external-modules/zip.md#external-zip) | 1.3.0 | `angie-module-zip` `angie-pro-module-zip` | Includes dynamic ZIP archive packaging. |
| [Zstd](https://en.angie.software//angie/docs/installation/external-modules/zstd.md#external-zstd) | f4ba115 | `angie-module-zstd` `angie-pro-module-zstd` | Includes Zstandard compression. |
# https://en.angie.software/genindex.md
# https://en.angie.software/angie/docs/installation/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/installation/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/|angie_version|
```
```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
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/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 source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild),
this module isn't built by default;
it should be enabled with the
`--with-google_perftools_module`
[build parameter](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure).
#### 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/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/news/gruppa-rubytech-i-angie-objedinaiut-resursi.md
# Rubytech Group and Russian Web Server Developer Angie Combine Resources and Expertise for Product Development
*22.08.2024*
Russian software developer for high-load systems Angie (Web Server LLC)
has joined the Rubytech Group of Companies.
*Russian software developer for high-load systems Angie (Web Server LLC) has joined the Rubytech Group of Companies. This strategic partnership will expand and enrich the group's product portfolio, as well as provide the developer with prospects for stable product development in accordance with the most current needs of the corporate segment.*
Since 2022, Angie has been developing its flagship product — a web server developed as a fork based on the world-renowned nginx (an open-source product). In just a few years, Angie's products have established a strong reputation among solutions for clustered software complexes and have earned market leader status in Russia. The company's products are included in the Register of Domestic Software.
As a result of the partnership, clients of the group will have the opportunity to build and develop their own IT infrastructure using high-performance and scalable Angie products, with implementation and reliable technical support provided by a team of experts, engineers, and system architects from Rubytech. In turn, Angie's development team will continue to develop the existing product portfolio and ensure the usual level of vendor support for solutions and services to current clients and partners. Both Angie's flagship products — the Angie PRO web server and the Kubernetes cloud environment solution Angie Ingress Controller (ANIC) — as well as the open-source version of the Angie web server will receive more intensive development.
*"Thanks to our collaboration with Rubytech, our commercial component will be strengthened by the years of experience and practice of the group's sales team. This will allow us not only to support and develop our own partner sales channels but also to reach a qualitatively new level.*
*This will enable us as a developer to quickly and confidently bring a new solution to market — the Angie Application Delivery Controller (Angie ADC) traffic balancing system, which will replace such Western software products as Citrix ADC/Netscaler, Radware, and F5 BIG-IP,"* comments **Zaur Abasmirzoev**, General Director of Angie (Web Server LLC).
*"In making the decision about the partnership, we primarily focused on the unique expertise of Angie's development team, which was at the origins of the world-class nginx web server.*
*I am confident that the consolidation of product, commercial, and managerial experience will benefit both parties. Angie's developers will have the opportunity to significantly scale their business and achieve sustainable growth and development: bring new products to market and make them in demand among corporate clients. In turn, the Rubytech group will be able to offer clients an even broader stack of technologies and solutions for building, developing, and scaling IT infrastructure.*
*I am confident that this alliance will be a successful and mutually beneficial investment and will contribute to the development of the group's business within the framework of a long-term strategy,"* shares plans for the future CEO of the Rubytech Group **Igor Vedekhin**.
# https://en.angie.software/angie/docs/installation/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
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/installation/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
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/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.
## 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, 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;
}
```
### auth_delay
| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `auth_delay` time; |
|------------------------------------------------------------------------------------------|------------------------|
| 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/installation/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; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| 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; |
|------------------------------------------------------------------------------------------|-------------------------------|
| 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; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| 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; |
|------------------------------------------------------------------------------------------|---------------------------------|
| 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; |
|------------------------------------------------------------------------------------------|--------------------------------|
| 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; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| 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 | `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; |
|------------------------------------------------------------------------------------------|------------------------------|
| 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. Variables can be used in the parameter value. |
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;
}
}
```
### 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 use 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#id4) 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; |
|------------------------------------------------------------------------------------------|--------------------------|
| 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.
### 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; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| 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; |
|------------------------------------------------------------------------------------------|--------------------------|
| 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; |
|------------------------------------------------------------------------------------------|-----------------------------|
| 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` 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];
```
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 [HTTP3 module](https://en.angie.software//angie/docs/configuration/modules/http/http_v3.md#http-v3) 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 a normalized 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.
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; |
|------------------------------------------------------------------------------------------|---------------------------------|
| 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; |
|------------------------------------------------------------------------------------------|---------------------------------|
| 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; |
|------------------------------------------------------------------------------------------|---------------------------|
| 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; |
|------------------------------------------------------------------------------------------|------------------------|
| 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; |
|------------------------------------------------------------------------------------------|-----------------------------|
| 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
| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `resolver` address ... [`valid=`time] [`ipv4=``on` | `off`] [`ipv6=``on` | `off`] [`status_zone=`zone]; |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------|
| Default | — |
| [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.
#### 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 only be specified once.
If it is repeated, the last definition takes effect.
By default, Angie caches answers using the TTL value of a response. If the `resolver` directive is not specified and no dynamic DNS queries are performed (for example, when using fixed names in [Proxy](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy) without variables), specifying a resolver is not required: names will be resolved at startup using the system resolver. The optional `valid` parameter allows overriding 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; |
|------------------------------------------------------------------------------------------|----------------------------------|
| 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;
```
### error_log_user_tag
| [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 records. The value is a [complex value](https://en.angie.software//angie/docs/configuration/configfile.md#syntax)
and can use 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).
### 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.
### 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; |
|------------------------------------------------------------------------------------------|------------------------|
| 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; |
|------------------------------------------------------------------------------------------|------------------------|
| 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; |
|------------------------------------------------------------------------------------------|------------------------------|
| 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; |
|------------------------------------------------------------------------------------------|----------------------------------------------------|
| 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; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| 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
| [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; |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| 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.
### 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'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.
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; |
|------------------------------------------------------------------------------------------|----------------------------------|
| 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; |
|------------------------------------------------------------------------------------------|-------------------------------|
| 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; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| 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; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| 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 (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
### `$time_iso8601`
local time in the ISO 8601 standard format
### `$time_local`
local time in the Common Log Format
### `$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
### `$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#id4), when doing internal redirects, or when using index files.
# https://en.angie.software/news/articles/http3-ebpf.md
# Solving nginx's HTTP/3 Architecture Problem: Angie's Experience and the Magic of eBPF
*29.01.2026*
How Angie 1.11 addressed the fundamental shortcomings of the HTTP/3
implementation in nginx: from simple hashes to building a full-fledged
accept() equivalent for QUIC using BPF programs.
*To the end user, switching from HTTP/2 to HTTP/3 may appear to be simply replacing TCP with UDP in the config. But for server software with a multi-process architecture, this step becomes a real headache. The classic* accept() *scheme that has underpinned TCP connection handling for years simply does not exist in the QUIC world. Packets arrive on a UDP port, and the OS kernel no longer knows which worker process should receive them.*
*In the original nginx, this resulted in HTTP/3 support remaining "experimental" and limited for a long time: it suffers from session disconnects and service degradation during configuration reloads. For many, this has been a dealbreaker for deploying the protocol in production.*
*In this article, we describe how Angie 1.11 addresses these fundamental shortcomings. We did not simply add protocol support — we rethought the way the server interacts with the kernel. The journey from simple hashes to building a full-fledged* accept() *equivalent for QUIC using BPF programs allows us to say: Angie's HTTP/3 implementation is complete, free of nginx's "teething problems", and fully ready for production use in high-load environments.*
*Welcome under the hood of modern data transport.*
---
*Now I hand it over to Vladimir, one of the developers of the HTTP/3 module in nginx, who is the author of the new mechanism and will share all the details.*
## Vladimir Khomutov
An nginx developer since 2012 and an Angie developer since 2022.
### Why HTTP/3 Is Nothing Like HTTP/{1,2}
The thing is, [HTTP/3](https://datatracker.ietf.org/doc/html/rfc9114) runs on top of the [QUIC](https://datatracker.ietf.org/doc/html/rfc9000) protocol, which is based on UDP, unlike previous HTTP versions that ran on top of TCP. In this article, we will not discuss how HTTP/3 differs in terms of semantics — there are no revolutions there. It is still URL requests with various methods, arguments, and headers, and responses with familiar status codes. Even though the wire representation has changed (it is now binary rather than text-based), the essence remains the same. What has truly changed, however, is the transport layer and how the application layer interacts with the transport protocol.
So, UDP. This means we are dealing with packets that may be lost or arrive out of order. There is also no flow control. In previous versions, all of these (and many other!) concerns were handled by the TCP stack, which is typically implemented in the OS kernel. Now the QUIC protocol takes on this responsibility. It handles packet numbering, tracks delivery order, and controls both the data transfer rate and packet sizes. Furthermore, it ensures data integrity through integrated cryptography. And today, all of this runs not in the kernel but in user space. It is possible that someday QUIC will make it into the kernel (such projects already exist) and we will return to the old paradigm, but for now Angie implements the entire QUIC and HTTP/3 stack on its own.
Thus, adopting QUIC means incorporating a large body of networking code tightly integrated with TLS into your application. The latter imposes additional requirements on the SSL library being used. The level of support for the required primitives varies widely across libraries, which can sometimes even lead to network-level incompatibilities.
Beyond the complexity, QUIC also brings new capabilities. For example, it can maintain connections when the client's or server's IP address changes ([migration](https://datatracker.ietf.org/doc/html/rfc9000#name-connection-migration)), provides greater [privacy](https://datatracker.ietf.org/doc/html/rfc9001), enables fast session resumption ([0-RTT](https://www.rfc-editor.org/rfc/rfc9001#section-4.6)), and supports truly independent data streams within a single connection. This is a significant improvement over HTTP/2, where a single lost packet in one stream would stall all others because they shared a single TCP connection (the Head-of-Line Blocking problem).
### How a TCP Server Works
Due to the architecture's reliance on multiple processes for multi-core systems, implementing the QUIC protocol presents challenges. To understand these, we first need to look at how client handling works in a TCP server. Consider this simple configuration:
```nginx
worker_processes 2;
events { }
http {
server {
listen 127.0.0.1:8080;
location / { return 200 "Hello, world\n"; }
}
}
```
First, the master process starts, reads the configuration, and creates a
listen socket. It then uses fork() to spawn two worker processes (one per
core). The worker processes wait for new connections in an infinite loop by
calling the accept() system call. When a client connects, one of the
processes receives a new client socket, which it uses for communication. The
OS kernel ensures that data from the client reaches the correct worker process
through this specific socket.
To go further, it is important to consider two more [procedures](https://en.angie.software//angie/docs/configuration/runtime.md#runtime) that significantly
affect operation: loading a new configuration and upgrading the binary without
service interruption (graceful reload and graceful upgrade). If you need to
change Angie's settings, you certainly do not want to stop the server and
drop existing connections. The same applies to upgrading the server version
itself.
How is a configuration update related to the TCP server? In Angie, to update settings, the user edits the configuration file and asks the system to apply the changes. At that point, the master process reads the new configuration and starts new worker processes that begin using it. The old processes continue to serve existing connections but no longer accept new requests because they close their listen sockets. At any given time, there may be multiple sets of worker processes, each operating with its own version of the configuration. New connections are handled only by the current worker processes.
For example, here is what you might see during a configuration update:
```text
$ ps aux|grep angie
root 26092 angie: master process v1.11.0 #1 [./sbin/angie]
nobody 26093 angie: worker process #1
nobody 26094 angie: worker process #1
nobody 26095 angie: worker process #1
nobody 26096 angie: worker process #1
# kill -HUP `cat logs/angie.pid`
$ ps aux|grep angie
root 26092 angie: master process v1.11.0 #2 [./sbin/angie]
nobody 26094 angie: worker process is shutting down #1
nobody 27084 angie: worker process #2
nobody 27085 angie: worker process #2
nobody 27086 angie: worker process #2
nobody 27087 angie: worker process #2
```
We see a master process running as the superuser and four worker processes running without privileges. The original processes were using configuration #1, while the new ones use configuration #2. One old process is still active — it has unfinished client connections.
The binary upgrade process is conceptually similar, but in this case a new master process is started (from the new executable), which spawns its own set of worker processes. The old and new masters run in parallel, each with its own set of worker processes. Existing connections continue to be served by the old processes until they finish, while new connections may land in either instance of the system (both old and new worker processes). Here is what the process table might look like during the transition:
```text
# ps aux|grep angie
root 101664 angie: master process v1.11.0 #1 [./sbin/angie]
nobody 101665 angie: worker process #1
nobody 101666 angie: worker process #1
nobody 101667 angie: worker process is shutting down #1
nobody 101668 angie: worker process #1
root 101676 angie: master process v1.11.0 #2 [./sbin/angie]
nobody 101753 angie: worker process #2
nobody 101754 angie: worker process #2
nobody 101755 angie: worker process #2
nobody 101756 angie: worker process #2
```
Here we have two master processes, each with its own set of worker processes,
with the second one already using the second generation of configuration.
You can always check the configuration generation in Angie via the [API](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#status-angie).
In both of these scenarios, the rule holds: existing connections continue to
be served by their original worker process, while new connections can be
accepted by the new processes. All of this is possible because the kernel
handles connection establishment, and new processes can claim connections
from it. Existing connections operate through already-created sockets that
belong to a specific process, so there is no room for confusion.
### How a UDP/QUIC Server Works
What changes with the move to QUIC? Now it is the Angie process, not the
kernel, that is responsible for accepting incoming connections. Instead of a
ready-made established connection obtained through an accept() call, we
simply receive UDP packets (from the listening socket). Their contents must
be correctly processed and attributed either to existing connections, to new
connections, or to noise.
Previously, there was an atomic way to accept a client connection (accept():
the kernel performs the TCP handshake and only notifies the application upon
success), but now we face a problem. To establish a connection, we need to
exchange a series of packets with the client within the same worker process.
However, a return packet may end up being received by a different worker
process, since it listens on the same socket. As a result, in the basic
scenario QUIC would only work with a single worker process (and even then with
caveats), which is obviously unacceptable for high-performance systems.
#### Binding Clients to Processes via reuseport
So we have multiple processes listening on the same port and reading UDP
packets from it. A packet read by one process may actually be intended for
another. Even if we determine that a packet is "not ours", we still don't
know where to forward it. This problem needs to be solved.
To solve it, we can use the reuseport socket option (which enables
[SO_REUSEPORT](https://lwn.net/Articles/542629/) or
SO_REUSEPORT_LB). Although its name and history can be misleading, on
modern systems it allows multiple processes to share an address:port pair.
Each process must have its own socket. In other words, instead of "1 socket
for N processes", we switch to "N sockets for N processes".
The kernel handles distributing incoming packets across sockets: it hashes
packet data (including the client's IP address and port) and uses the result
to select a socket from the reuseport group. Thanks to this, an unchanged
client always lands on the same socket and therefore in the correct worker
process. Using the reuseport option in the listen directive:
```nginx
worker_processes 2;
events { }
http {
ssl_certificate ...
ssl_certificate_key ...
server {
listen 127.0.0.1:8080 quic reuseport;
location / { return 200 "Hello, world\n"; }
}
}
```
While this approach works, it is not ideal:
- **Uneven distribution:** the distribution of clients across the IP address
space may not be random, causing the load to be spread unevenly across
worker processes.
- **Address changes:** a client's IP address may change either due to QUIC
migration mechanisms or NAT behavior.
- **Update process:** complex scenarios involving configuration or binary
updates bring back the original problem — socket sharing between multiple
sets of processes. This happens because after the master process calls
fork(), sockets are inherited and shared between different generations of
worker processes.
#### Binding Clients to Processes via BPF
To address these problems, the [BPF module](https://en.angie.software//angie/docs/configuration/modules/http/http_v3.md#quic-bpf) was introduced.
This is a Linux-specific [technology](https://docs.cilium.io/en/latest/reference-guides/bpf/index.html) that
allows an application to intervene in the kernel's socket selection process for
an incoming packet. This functionality extends the capabilities of reuseport:
instead of simply distributing packets by hash, it allows loading a custom
socket selection algorithm into the kernel. The diagram below illustrates how
this works.
How does this algorithm work? In the first version (still in nginx), for
simplicity, client QUIC connections were bound to the worker process number.
This was implemented as follows: each QUIC packet contains a [Destination
Connection ID (DCID)](https://datatracker.ietf.org/doc/html/rfc9000#name-connection-id) — a
destination identifier that may change during the lifetime of a connection. We
used this property to encode the socket identifier (obtained via SO_COOKIE)
directly into the DCID.
The BPF module created a table in the kernel that mapped sockets to their
identifiers. The table size was fixed and determined by the number of processes
in the original configuration (with a small margin). The program analyzed each
QUIC packet, extracted the DCID, and used it to determine which socket should
receive the packet. New packets (without a DCID) could be directed to any
socket. Enabling BPF is done by adding the quic_bpf on directive to the
configuration:
```nginx
worker_processes 2;
events { }
quic_bpf on;
http {
ssl_certificate ...
ssl_certificate_key ...
server {
listen 127.0.0.1:8080 quic reuseport;
location / { return 200 "Hello, world\n"; }
}
}
```
In essence, this is analogous to the [sticky cookie](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky) mechanism in load balancers. This solved the client migration problem, but still performed poorly in complex scenarios. Moreover, this scheme exposed internal worker process implementation details to the outside world. It also broke down when new master processes were started during binary upgrades. And during configuration reloads, new packets could still end up at old worker processes.
To minimize the negative effects, old worker processes were made to either not respond to new connection requests or respond with a retry packet. This was based on the assumption that the client would make several attempts, and over time (once its port changed or the old processes terminated) it would reach a new worker process where it could successfully establish a connection. Of course, this solution was not ideal and led to temporary service degradation after a configuration reload.
#### Using Client Sockets
At some point, it became clear that each client needed its own socket — just
like with TCP. In effect, we needed an accept() equivalent for QUIC. This
approach was implemented using BPF in recent versions of Angie. It solved the
problems that arose during configuration and binary updates. The diagram below
shows the new approach — as you can see, it is considerably more complex than
the previous one.
Now the BPF module is aware of how many Angie instances are running and how many worker processes each one has. Each instance maintains a table of accepted connections (mapping unmodified DCIDs to specific client sockets). In addition, the kernel maintains a table of listening sockets for each instance.
Every packet destined for a port that Angie listens on with the quic option first passes through the BPF program. It runs a socket (and therefore worker process) selection procedure by checking conditions in sequence:
1. **Session ID present:** if the packet contains a known session identifier, the socket of the existing connection is selected.
2. **New connection:** if no session is found, the packet is treated as a new connection request.
3. **Instance selection:** for new connections, an Angie instance is chosen at random to handle them (if more than one master is running).
4. **Socket selection:** the client's hash is then used to select a listening socket from that specific instance.
Now, when a worker process receives a new connection request on its listening socket, it creates a new client socket and adds an entry with the corresponding DCID to the BPF table. This guarantees that all subsequent packets will be delivered to that exact socket.
When an instance shuts down, the worker process closes the listening socket, removes its entries from the BPF tables, and stops accepting new requests, while existing connections continue to work without interruption. During a configuration reload or new master launch, both old and new processes correctly update the kernel tables, allowing the BPF module to route traffic accurately in any situation.
### Configuring the BPF Module
An important note: by enabling the BPF module in the configuration, you are not simply changing Angie's internal settings — you are also modifying global kernel objects (attached to the reuseport socket group). Once BPF is enabled, it cannot be disabled without a full process restart. Even if you remove it from the new configuration, the program loaded by the previous version will remain in the kernel.
The active connections table size is limited and calculated using the formula: N = worker_connections x MAX_SERVER_IDS, where:
* worker_connections is the value of the corresponding directive in the configuration at the time the BPF tables were created;
* MAX_SERVER_IDS is the maximum number of QUIC Server IDs per connection (currently a preset value of 8).
A clarification is needed here: the Connection ID in the QUIC protocol may change multiple times during a session to make it harder to track the existence of a connection (for enhanced privacy). Therefore, at any given moment, more than one ID may be associated with a particular connection. And MAX_SERVER_IDS defines the limit on the number of such simultaneously active identifiers.
### Conclusion
In summary, the transition to HTTP/3 is not simply a protocol version change — it is a fundamental shift in the web data transport paradigm. The main challenge lies not in HTTP semantics, which have remained the same, but in the need to adapt server software to a fundamentally different connection model based on QUIC and UDP.
Here are the key architectural differences when using HTTP/1, 2, and HTTP/3 in Angie today:
| | **HTTP/1.1** | **HTTP/2** | **HTTP/3** |
|---------------------------------------|-----------------------------------------------------|-----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Representation** | Text | Binary | Binary |
| **Transport** | TCP | TCP | QUIC over UDP |
| **Security** | TLS over TCP | TLS over TCP | QUIC (TLS integrated into the protocol) |
| **Network stack (transport layer)** | Kernel implementation (SOCK_STREAM sockets) | Kernel implementation (SOCK_STREAM sockets) | Implemented in Angie (on top of SOCK_DGRAM sockets) |
| **Streams within a connection** | None | Present but may block each other (HoL) | Streams are independent |
| **Encryption** | Optional | Optional\* | Integral part of the protocol |
| **Process selection for connections** | Chosen by the kernel (via the accept() system call) | Chosen by the kernel (via the accept() system call) | Chosen by the BPF module upon receiving a UDP packet, based on connection data from Angie |
| **Protocol selection by client** | Default port 80, ALPN list for TLS on port 443 | Default port 80, ALPN list for TLS on port 443 | Alt-Svc header in the response, protocol list in DNS records |
| **Compatibility** | All supported OSes | All supported OSes | BPF module is available only on Linux; on other OSes, support is limited (single worker process, configuration changes may interrupt existing connections) |
Unlike TCP, where the operating system kernel takes on all the complexity of managing connections and balancing them between processes, in the QUIC world this responsibility falls on the application itself. As we have seen with Angie, this gives rise to a number of non-trivial challenges: from initial packet balancing to supporting complex scenarios such as connection migration and seamless configuration or binary updates.
The evolution of solutions in Angie — from the primitive SO_REUSEPORT approach inherited from nginx to the sophisticated system with individual client sockets and multiple BPF tables — clearly demonstrates how new standards are integrated into time-tested multi-process architectures. The key achievement was creating an accept() equivalent for QUIC using eBPF, which allowed the system to return to the familiar and reliable connection handling model. Despite the increased complexity and dependence on Linux-specific capabilities, this approach paves the way for stable, high-performance HTTP/3 operation in high-load environments.
# 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.
## 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
Examples of configuration and setup instructions can be found in the [ACME Configuration](https://en.angie.software//angie/docs/configuration/acme.md#acme-config) section.
## Directives
### acme
#### Versionchanged
Changed in version 1.9.0: The "no valid domain name defined for ACME client" error is issued only
if no valid (i.e. ACME-compliant) domain name is found in the
[server](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server) block that references the ACME client.
| [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 domains in this [server](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server) block.
A single certificate covers all domains 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, new certificates are requested for all domains
that are missing a valid certificate.
Possible reasons include certificate expiration,
missing or unreadable files,
and changes in certificate settings.
#### NOTE
This directive only controls which domain names
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`.
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.9.0.
#### Versionchanged
Changed in version 1.11.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=`number] [`max_key_auth_size=`size] [`renew_before_expiry=`time] [`renew_on_load`] [`retry_after_error=`off|time] [`challenge=``dns` | `http` | `alpn`] [`account_key=`file]; |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 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,
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 in bytes to reserve space for the new certificate in shared memory; the more domains the certificate is requested for, the more space is required. 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#syntax) 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#syntax) 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`. |
| `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`. |
| `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. |
### 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; |
|------------------------------------------------------------------------------------------|----------------------------------|
| 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`.
### 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
#### Versionchanged
Changed in version 1.9.1.
| [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 must run with [superuser](https://en.angie.software//angie/docs/configuration/modules/core.md#user) privileges.
### 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 must run with [superuser](https://en.angie.software//angie/docs/configuration/modules/core.md#user) privileges.
### acme_hook
#### Versionchanged
Changed in version 1.9.0.
| [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 ...;
```
## 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),
this module isn't built by default;
it should be enabled with the
`‑‑with‑http_addition_module`
[build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure).
In packages and images from [our repos](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_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.
### 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.
### 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
[limit_conn http](https://en.angie.software//angie/docs/configuration/modules/http/http_limit_conn.md#http-limit-conn), [limit_conn stream](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.
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.
## 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 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":"|version|",
"address":"192.168.16.5",
"generation":1,
"load_time":"|sampledateshort|T12: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":"|version|",
"address":"192.168.16.5",
"generation":1,
"load_time":"|sampledateshort|T12: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
},
"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
```
#### NOTE
By default, the module uses ISO 8601 format strings for dates;
to use the integer UNIX epoch format instead,
add the `date=epoch` parameter to the query string:
```console
$ curl https://www.example.com/status/angie/load_time
"2024-04-01T00:59:59+01:00"
$ curl https://www.example.com/status/angie/load_time?date=epoch
1711929599
```
### Server status
#### `/status/angie`
#### Versionchanged
Changed in version 1.9.0: The `build_time` field was added.
```json
{
"version": "|version|",
"build_time": "|sampledateshort|T16:05:43.805Z",
"address": "192.168.16.5",
"generation": 1,
"load_time": "|sampledateshort|T16: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; total number of configuration reloads since last start |
| `load_time` | String; time of the last configuration reload in the [date](#api-date-format) format; string values have millisecond resolution |
| `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:
#### 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), such as [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):
```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 |
|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| :samp: 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 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 |
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 |
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#id3)
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 [$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:
| `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
}
}
```
### 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 current size of the cache |
|---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `max_size` | Number; configured limit on the maximum size of the cache |
| `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:
| `shards` | Object; lists individual shards as members |
|------------|---------------------------------------------------------------------|
| `` | Object; represents an individual shard with its cache path for name |
| `size` | Number; the shard's current size |
| `max_size` | Number; maximum shard size, if configured |
| `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": "|sampledateshort|T16: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;
}
```
#### `/status/http/upstreams/`
#### Versionchanged
Changed in version 1.9.0: The `busy` peer state was added.
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
},
"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; - `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; - `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; - `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 (PRO)](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 (PRO)](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 |
| `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": "|sampledateshort|T09: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;
}
```
#### `/status/stream/upstreams/`
#### Versionchanged
Changed in version 1.9.0: The `busy` peer state was added.
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
}
}
}
}
```
| `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 - `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 - `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 - `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 (PRO)](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 (PRO)](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 (PRO)](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-response-time-factor) directive |
| `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": "|sampledateshort|T11: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) |
## 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` (PRO) 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."
}
```
#### NOTE
Even with a compatible load balancing method, the `backup` parameter
can only be set when adding a new peer.
#### `/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` (PRO) 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."
}
```
#### NOTE
Even with a compatible load balancing method, the `backup` parameter
can only be set when adding a new peer.
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` 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": ""
}
}
```
#### 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.
## 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.
| `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),
this module isn't built by default;
it should be enabled with the
`‑‑with‑http_auth_request_module`
[build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure).
In packages and images from [our repos](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 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.
## 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` | Object size according to [autoindex_exact_size](#autoindex-exact-size); for directories — `0` |
| `mtime` | Last modification time in Unix time format |
HTML
```html
Index of /files/
```
XML
```xml
example.txtfile12342025-06-12T14:21:00Zimage.pngfile43212025-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.
## Variables
### `$modern_browser`
equals the value set by the [modern_browser_value](#modern-browser-value) directive, if a browser was identified as modern;
### `$ancient_browser`
equals the value set by the [ancient_browser_value](#ancient-browser-value) directive, if a browser was identified as ancient;
### `$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.
## 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),
this module isn't built by default;
it should be enabled with the
`‑‑with‑http_dav_module`
[build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure).
In packages and images from [our repos](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).
If a container description contains a label with a port,
then the address and port of such a container,
as well as parameters from other labels of this container,
are automatically added 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 ports.
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 specified Docker network
(or the first available one if the `angie.network` label is not specified)
is added to the corresponding proxied server group.
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)* | Container port that Angie will connect to; the container itself is added to the group named ``. |
| `angie.network=` | Name of the Docker network from which to take the container's IP address. |
| `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=
