hannah-eee/nginx-docs huggingface dataset:
Contributing Changes

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Contributing Changes

Getting Sources
Formatting Changes
Before Submitting
Submitting Changes
Website
License

Getting Sources

GitHub is used
to store source code.
The repository can be cloned
with the following command:

git clone https://github.com/nginx/nginx.git

Formatting Changes

Changes should be formatted according to the
code style
used by nginx.
Sometimes, there is no clear rule; in such cases
examine how existing nginx sources are formatted and mimic this style.
Changes will more likely be accepted if style corresponds to the surrounding
code.

Commit
the changes in your nginx GitHub fork.
Please ensure that the specified
e-mail
address and real name of the author are correct.

The commit message should have a single-line synopsis followed by verbose
description after an empty line.
Limit the subject and commit message body lines to 72 characters.
The resulting commit can be obtained using the
git show command:

commit 067d766f210ee914b750d79d9284cbf8801058f3
Author: Zoey <username@example.com>
Date: Sun Apr 5 11:31:15 2026 +0200

Fix $request_port and $is_request_port in subrequests

Closes #1247.

diff --git a/src/http/ngx_http_core_module.c b/src/http/ngx_http_core_module.c
index 0c46106db..53ddf39bb 100644
--- a/src/http/ngx_http_core_module.c
+++ b/src/http/ngx_http_core_module.c
@@ -2453,6 +2453,8 @@ ngx_http_subrequest(ngx_http_request_t *r,
sr->method = NGX_HTTP_GET;
sr->http_version = r->http_version;

+ sr->port = r->port;
+
sr->request_line = r->request_line;
sr->uri = *uri;

Before Submitting

Several points are worth to consider before submitting changes:

The proposed changes should work properly on a wide range of
supported
platforms.

Try to make it clear why the suggested change is needed, and provide a use
case, if possible.

Passing your changes through the test suite is a good way to ensure
that they do not cause a regression.
The repository with
tests can be cloned with the following command:

git clone https://github.com/nginx/nginx-tests.git

Submitting Changes

The proposed changes should be submitted from your fork to
nginx repository
as a
pull request.

Website

GitHub is used to store the sources for this website.
The repository
can be cloned with the following command:

git clone https://github.com/nginx/nginx.org.git

Documentation changes should be submitted from your fork
as a pull request.

License

Submitting changes implies granting project a permission to use it under
an appropriate license.
A debugging log

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

A debugging log

Debugging log for selected clients
Logging to a cyclic memory buffer

To enable a debugging log, nginx needs to be configured to support
debugging during the build:

./configure --with-debug ...

Then the debug level should be set with the
error_log directive:

error_log /path/to/log debug;

To verify that nginx is configured to support debugging,
run the nginx -V command:

configure arguments: --with-debug ...

Pre-built Linux packages
provide out-of-the-box support for debugging log with
the nginx-debug binary (1.9.8)
which can be run using commands

service nginx stop
service nginx-debug start

and then set the debug level.
The nginx binary version for Windows is always built with the debugging log
support, so only setting the debug level will suffice.

Note that redefining the log without also specifying the
debug
level will disable the debugging log.
In the example below, redefining the log on the
server
level disables the debugging log for this server:

error_log /path/to/log debug;

http {
server {
error_log /path/to/log;
...

To avoid this, either the line redefining the log should be
commented out, or the debug level specification should
also be added:

error_log /path/to/log debug;

http {
server {
error_log /path/to/log debug;
...

Debugging log for selected clients

It is also possible to enable the debugging log for
selected
client addresses only:

error_log /path/to/log;

events {
debug_connection 192.168.1.1;
debug_connection 192.168.10.0/24;
}

Logging to a cyclic memory buffer

The debugging log can be written to a cyclic memory buffer:

error_log memory:32m debug;

Logging to the memory buffer on the debug level
does not have significant impact on performance even under high load.
In this case, the log can be extracted using
a gdb script like the following one:

set $log = ngx_cycle->log

while $log->writer != ngx_log_memory_writer
set $log = $log->next
end

set $buf = (ngx_log_memory_buf_t *) $log->wdata
dump binary memory debug_log.txt $buf->start $buf->end

Or using an lldb script as follows:

expr ngx_log_t *$log = ngx_cycle->log
expr while ($log->writer != ngx_log_memory_writer) { $log = $log->next; }
expr ngx_log_memory_buf_t *$buf = (ngx_log_memory_buf_t *) $log->wdata
memory read --force --outfile debug_log.txt --binary $buf->start $buf->end
Connection processing methods

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Connection processing methods

nginx supports a variety of connection processing methods.
The availability of a particular method depends on the platform used.
On platforms that support several methods nginx will normally
select the most efficient method automatically.
However, if needed, a connection processing method can be selected
explicitly with the
use directive.

The following connection processing methods are supported:

select — standard method.
The supporting module is built automatically on platforms that lack
more efficient methods.
The --with-select_module and
--without-select_module configuration parameters
can be used to forcibly enable or disable the build of this module.

poll — standard method.
The supporting module is built automatically on platforms that lack
more efficient methods.
The --with-poll_module and
--without-poll_module configuration parameters
can be used to forcibly enable or disable the build of this module.

kqueue — efficient method used on
FreeBSD 4.1+, OpenBSD 2.9+, NetBSD 2.0, and macOS.

epoll — efficient method used on
Linux 2.6+.

The EPOLLRDHUP (Linux 2.6.17, glibc 2.8)
and EPOLLEXCLUSIVE (Linux 4.5, glibc 2.24)
flags are supported since 1.11.3.

Some older distributions like SuSE 8.2 provide patches
that add epoll support to 2.4 kernels.

/dev/poll — efficient method used on
Solaris 7 11/99+, HP/UX 11.22+ (eventport), IRIX 6.5.15+,
and Tru64 UNIX 5.1A+.

eventport — event ports, method
used on Solaris 10+ (due to known issues,
it is recommended using the /dev/poll method instead).
FAQ

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

FAQ

I am trying to open Facebook, Yahoo!, Yandex, Tumblr, Google etc., and instead I am getting “Welcome to nginx!” page

How can nginx copyright be acknowledged when using nginx as part of a proprietary software distribution?

What does the following error mean in the log file: “accept() failed (53: Software caused connection abort) while accepting new connection on 0.0.0.0:80”?

Is there a proper way to use nginx variables to make sections of the configuration shorter, using them as macros for making parts of configuration work as templates?

Can I run nginx with “daemon off” or “master_process off” settings in a production environment?

Why nginx doesn’t handle chunked encoding responses from my backend properly?

A message “ ‘sys_errlist’ is deprecated; use ‘strerror’ or ‘strerror_r’ instead ”
Setting up hashes

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Setting up hashes

To quickly process static sets of data such as server names,
map directive’s values,
MIME types, names of request header strings,
nginx uses hash tables.
During the start and each re-configuration nginx selects the
minimum possible sizes of hash tables such that the bucket size
that stores keys with identical hash values does not exceed the
configured parameter (hash bucket size).
The size of a table is expressed in buckets.
The adjustment is continued until the table size exceeds the
hash max size parameter.
Most hashes have the corresponding directives that allow changing
these parameters, for example, for the server names hash they are
server_names_hash_max_size
and server_names_hash_bucket_size.

The hash bucket size parameter is aligned to the size that is a
multiple of the processor’s cache line size. This speeds up
key search in a hash on modern processors by reducing the number
of memory accesses.
If hash bucket size is equal to one processor’s cache line size
then the number of memory accesses during the key search will be
two in the worst case — first to compute the bucket address,
and second during the key search inside the bucket.
Therefore, if nginx emits the message requesting to increase
either hash max size or hash bucket size then the first parameter
should first be increased.
Building nginx on the Win32 platform with Visual C

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Building nginx on the Win32 platform with Visual C

Build steps
See also

Prerequisites

To build nginx on the Microsoft Win32® platform you need:

Microsoft Visual C compiler. Microsoft Visual Studio®
8, 10, 17 are known to work.

MSYS or
MSYS2.

Perl, if you want to build OpenSSL® and nginx with SSL support.
For example ActivePerl
or Strawberry Perl.

Git client.

PCRE, zlib
and OpenSSL libraries sources.

Build steps

Ensure that paths to Perl, Git and MSYS bin directories are added to
PATH environment variable before you start build. To set Visual C environment
run vcvarsall.bat script from Visual C directory.

To build nginx:

Start MSYS bash.

Check out nginx sources from the GitHub repository:

git clone https://github.com/nginx/nginx.git

Create a build and lib directories, and unpack zlib, PCRE and OpenSSL libraries
sources into lib directory:

mkdir objs
mkdir objs/lib
cd objs/lib
tar -xzf ../../pcre2-10.39.tar.gz
tar -xzf ../../zlib-1.3.1.tar.gz
tar -xzf ../../openssl-3.0.14.tar.gz

Run configure script:

auto/configure \
--with-cc=cl \
--with-debug \
--prefix= \
--conf-path=conf/nginx.conf \
--pid-path=logs/nginx.pid \
--http-log-path=logs/access.log \
--error-log-path=logs/error.log \
--sbin-path=nginx.exe \
--http-client-body-temp-path=temp/client_body_temp \
--http-proxy-temp-path=temp/proxy_temp \
--http-fastcgi-temp-path=temp/fastcgi_temp \
--http-scgi-temp-path=temp/scgi_temp \
--http-uwsgi-temp-path=temp/uwsgi_temp \
--with-cc-opt=-DFD_SETSIZE=1024 \
--with-pcre=objs/lib/pcre2-10.39 \
--with-zlib=objs/lib/zlib-1.3.1 \
--with-openssl=objs/lib/openssl-3.0.14 \
--with-openssl-opt=no-asm \
--with-http_ssl_module

Run make:

nmake

See also

nginx for Windows
Installing nginx

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Installing nginx

nginx can be installed differently, depending on the operating system.

Installation on Linux

For Linux, nginx packages
from nginx.org can be used.

Installation on FreeBSD

On FreeBSD, nginx can be installed either from the packages
or through the
ports
system.
The ports system provides greater flexibility, allowing selection among
a wide range of options.
The port will compile nginx with the specified options and install it.

Building from Sources

If some special functionality is required, not available with packages and
ports, nginx can also be compiled from source files.
While more flexible, this approach may be complex for a beginner.
For more information, see Building nginx from Sources.
Module ngx_google_perftools_module

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Module ngx_google_perftools_module

Example Configuration
Directives
google_perftools_profiles

The ngx_google_perftools_module module (0.6.29) enables
profiling of nginx worker processes using
Google Performance Tools.
The module is intended for nginx developers.

This module is not built by default, it should be enabled with the
--with-google_perftools_module
configuration parameter.

This module requires the
gperftools library.

Example Configuration

google_perftools_profiles /path/to/profile;

Profiles will be stored as
/path/to/profile.<worker_pid>.

Directives

Syntax:

google_perftools_profiles file;

Default:

—

Context:

main

Sets a file name that keeps profiling information of
nginx worker process.
The ID of the worker process is always a part of the file name
and is appended to the end of the file name, after a dot.
Command-line parameters

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Command-line parameters

nginx supports the following command-line parameters:

-? | -h — print help
for command-line parameters.

-c file — use an alternative
configuration file instead of a default file.

-e file — use an alternative
error log file to store the log
instead of a default file (1.19.5).
The special value stderr selects the standard error file.

-g directives — set
global configuration directives,
for example,

nginx -g "pid /var/run/nginx.pid; worker_processes `sysctl -n hw.ncpu`;"

-l port — enable
nginx control REST API
on a specified port or UNIX-domain socket (1.29.8).

This parameter is available as part of our
commercial subscription.

-p prefix — set nginx path prefix,
i.e. a directory that will keep server files
(default value is /usr/local/nginx).

-q — suppress non-error messages
during configuration testing.

-s signal — send a signal
to the master process.
The argument signal can be one of:

stop — shut down quickly

quit — shut down gracefully

reload — reload configuration,
start the new worker process with a new configuration,
gracefully shut down old worker processes.

reopen — reopen log files

-t — test the configuration file: nginx checks the
configuration for correct syntax, and then tries to open files
referred in the configuration.

-T — same as -t,
but additionally dump configuration files to standard output (1.9.2).

-v — print nginx version.

-V — print nginx version, compiler version,
and configure parameters.
Configuration file measurement units

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Configuration file measurement units

Sizes and offsets
Time intervals

nginx supports several measurement units for specifying
sizes, offsets, and time intervals within configuration files.

Sizes and offsets

Sizes can be specified in bytes, kilobytes, or megabytes
using the following suffixes:

k and K for kilobytes

m and M for megabytes

For example,
“1024”, “8k”, “1m”.

Offsets can be also specified in gigabytes using the
g or G suffixes.

Time intervals

Time intervals can be specified in milliseconds, seconds,
minutes, hours, days and so on, using the following suffixes:

ms	milliseconds

s	seconds (default)

m	minutes

h	hours

d	days

w	weeks

M	months, 30 days

y	years, 365 days

Multiple units can be combined in a single value
by specifying them in the order from the most to the least significant,
and optionally separated by whitespace.
For example, “1h 30m” specifies the same time
as “90m” or “5400s”.

A value without a suffix means seconds.

It is recommended to always specify a suffix.

Certain time intervals can be specified only with a seconds resolution.
Logging to syslog

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Logging to syslog

The
error_log
and
access_log
directives support logging to syslog.
The following parameters configure logging to syslog:

server=address

Defines the address of a syslog server.
The address can be specified as a domain name or IP address,
with an optional port, or as a UNIX-domain socket path
specified after the “unix:” prefix.
If port is not specified, the UDP port 514 is used.
If a domain name resolves to several IP addresses, the first resolved
address is used.

facility=string

Sets facility of syslog messages, as defined in
RFC 3164.
Facility can be one of “kern”, “user”,
“mail”, “daemon”,
“auth”, “intern”,
“lpr”, “news”, “uucp”,
“clock”, “authpriv”,
“ftp”, “ntp”, “audit”,
“alert”, “cron”,
“local0”..“local7”.
Default is “local7”.

severity=string

Sets severity of syslog messages for
access_log,
as defined in
RFC 3164.
Possible values are the same as for the second parameter (level) of the
error_log directive.
Default is “info”.

Severity of error messages is determined by nginx, thus the parameter
is ignored in the error_log directive.

tag=string

Sets the tag of syslog messages.
Default is “nginx”.

nohostname

Disables adding the “hostname” field into the syslog message header (1.9.7).

Example syslog configuration:

error_log syslog:server=192.168.1.1 debug;

access_log syslog:server=unix:/var/log/nginx.sock,nohostname;
access_log syslog:server=[2001:db8::1]:12345,facility=local7,tag=nginx,severity=info combined;

Logging to syslog is available since version 1.7.1.
As part of our
commercial subscription
logging to syslog is available since version 1.5.3.
A message “ ‘sys_errlist’ is deprecated; use ‘strerror’ or ‘strerror_r’ instead ”

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

A message “ ‘sys_errlist’ is deprecated; use ‘strerror’ or ‘strerror_r’ instead ”

Q:
While building nginx version 0.7.66, 0.8.35 or higher on Linux
the following warning messages are issued:

warning: `sys_errlist' is deprecated;
use `strerror' or `strerror_r' instead
warning: `sys_nerr' is deprecated;
use `strerror' or `strerror_r' instead

A:
This is normal: nginx has to use the deprecated sys_errlist[] and sys_nerr
in signal handlers because strerror() and strerror_r() functions
are not Async-Signal-Safe.
nginx for Windows

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

nginx for Windows

Known issues
Possible future enhancements

Version of nginx for Windows uses the native Win32 API (not the Cygwin emulation
layer).
Only the select() and poll() (1.15.9)
connection processing methods are currently used,
so high performance and scalability should not be expected.
Due to this and some other known issues version of nginx for Windows
is considered to be a beta version.
At this time, it provides almost the same functionality as a UNIX version
of nginx except for
XSLT filter, image filter, GeoIP module, and embedded Perl language.

To install nginx/Windows, download
the latest mainline version distribution (1.31.0),
since the mainline branch of nginx contains all known fixes.
Then unpack the distribution, go to the
nginx-1.31.0
directory, and run nginx.
Here is an example for the drive C: root directory:

cd c:\
unzip nginx-1.31.0.zip
cd nginx-1.31.0
start nginx

Run the tasklist command-line utility
to see nginx processes:

C:\nginx-1.31.0>tasklist /fi "imagename eq nginx.exe"

Image Name PID Session Name Session# Mem Usage
=============== ======== ============== ========== ============
nginx.exe 652 Console 0 2 780 K
nginx.exe 1332 Console 0 3 112 K

One of the processes is the master process and another is the worker process.
If nginx does not start, look for the reason in
the error log file logs\error.log.
If the log file has not been created, the reason for this should be reported
in the Windows Event Log.
If an error page is displayed instead of the expected page, also look
for the reason in the logs\error.log file.

nginx/Windows uses the directory where it has been run as the prefix
for relative paths in the configuration.
In the example above, the prefix is
C:\nginx-1.31.0\.
Paths in a configuration file must be specified in UNIX-style using
forward slashes:

access_log logs/site.log;
root C:/web/html;

nginx/Windows runs as a standard console application (not a service),
and it can be managed using the following commands:

nginx -s stop
fast shutdown

nginx -s quit
graceful shutdown

nginx -s reload

changing configuration,
starting new worker processes with a new configuration,
graceful shutdown of old worker processes

nginx -s reopen
re-opening log files

Known issues

Although several workers can be started, only one of them
actually does any work.

The UDP (and, inherently, QUIC) functionality is not supported.

Possible future enhancements

Running as a service.

Using the I/O completion ports as a connection processing method.

Using multiple worker threads inside a single worker process.
What does the following error mean in the log file: “accept() failed (53: Software caused connection abort) while accepting new connection on 0.0.0.0:80”?

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

What does the following error mean in the log file: “accept() failed (53: Software caused connection abort) while accepting new connection on 0.0.0.0:80”?

Q:
What does the following error mean in the log file: "accept() failed (53:
Software caused connection abort) while accepting new
connection on 0.0.0.0:80"?

A:
Such errors stem from the connections that the clients managed
to close before nginx was able to process them. For instance, this can
happen in a situation when the user didn’t wait for a page
heavily populated with images to load fully, and clicked on a
different link. In this case user’s browser would close all of
the prior connections which aren’t longer necessary.
It is a non-critical error.
Why nginx doesn’t handle chunked encoding responses from my backend properly?

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Why nginx doesn’t handle chunked encoding responses from my backend properly?

Q:
My backend server appears to send HTTP/1.0 responses using
chunked encoding but nginx doesn’t handle it correctly.
For instance, I’m using nginx as a frontend to my node.js
application and instead of pure JSON from backend, nginx
returns something framed in decimal numbers like

47
{"error":"query error","message":"Parameter(s) missing: user,password"}
0

A:
Your backend violates HTTP specification (see
RFC 2616,
"3.6 Transfer Codings").
The "chunked" transfer-codings must not be used with HTTP/1.0.
You’d need to either fix your backend application or upgrade
to nginx version 1.1.4 and newer, where an additional code
was introduced to handle such erratic backend behavior.
Can I run nginx with “daemon off” or “master_process off” settings in a production environment?

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Can I run nginx with “daemon off” or “master_process off” settings in a production environment?

Q:
Can I run nginx with "daemon off" or "master_process off" settings
in a production environment?

A:
First of all, both "daemon on|off" and "master_process on|off" directives were
intended to be used primarily for nginx code development.

While many people use "daemon off" in production it wasn’t really meant for
that. Since version 1.0.9 it is now quite safe to run nginx in production
with "daemon off", though. Bear in mind that non-stop upgrade is not an
option with "daemon off".

In a development environment, using "master_process off", nginx can run in
the foreground without the master process and can be terminated simply
with ^C (SIGINT). This is somewhat similar to running Apache with
an 'X' command-line option. However you should NEVER run nginx in production
with "master_process off".
How can nginx copyright be acknowledged when using nginx as part of a proprietary software distribution?

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

How can nginx copyright be acknowledged when using nginx as part of a proprietary software distribution?

Q:
I’d like to use nginx distribution as part of my proprietary
software package. How can nginx copyright be acknowledged
when using nginx as part of a proprietary software distribution?

A:
The text below should be added to your license conditions,
followed by the text of the applicable 2-clause BSD license described
here.

This product contains software provided by Nginx, Inc. and its contributors.

Also, if your build of nginx includes any of the following 3rd party
products: zlib, PCRE, OpenSSL — it’s worth including their
copyright acknowledgements and disclaimers as well.
Is there a proper way to use nginx variables to make sections of the configuration shorter, using them as macros for making parts of configuration work as templates?

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Is there a proper way to use nginx variables to make sections of the configuration shorter, using them as macros for making parts of configuration work as templates?

Q:
Is there a proper way to use nginx variables to make sections of
the configuration shorter, using them as macros for making
parts of configuration work as templates?

A:
Variables should not be used as template macros. Variables are
evaluated in the run-time during the processing of each
request, so they are rather costly compared to plain static
configuration. Using variables to store static strings is also
a bad idea. Instead, a macro expansion and "include" directives
should be used to generate configs more easily and it can be
done with the external tools, e.g. sed + make or any other
common template mechanism.
Converting rewrite rules

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Converting rewrite rules

Converting Mongrel rules

A redirect to a main site

People who during their shared hosting life used to configure
everything using only Apache’s .htaccess files,
usually translate the following rules:

RewriteCond %{HTTP_HOST} example.org
RewriteRule (.*) http://www.example.org$1

to something like this:

server {
listen 80;
server_name www.example.org example.org;
if ($http_host = example.org) {
rewrite (.*) http://www.example.org$1;
}
...
}

This is a wrong, cumbersome, and ineffective way.
The right way is to define a separate server for example.org:

server {
listen 80;
server_name example.org;
return 301 http://www.example.org$request_uri;
}

server {
listen 80;
server_name www.example.org;
...
}

On versions prior to 0.9.1, redirects can be made with:

rewrite ^ http://www.example.org$request_uri?;

Another example.
Instead of the “upside-down” logic “all that is not
example.com and is not www.example.com”:

RewriteCond %{HTTP_HOST} !example.com
RewriteCond %{HTTP_HOST} !www.example.com
RewriteRule (.*) http://www.example.com$1

one should simply define example.com, www.example.com,
and “everything else”:

server {
listen 80;
server_name example.com www.example.com;
...
}

server {
listen 80 default_server;
server_name _;
return 301 http://example.com$request_uri;
}

On versions prior to 0.9.1, redirects can be made with:

rewrite ^ http://example.com$request_uri?;

Converting Mongrel rules

Typical Mongrel rules:

DocumentRoot /var/www/myapp.com/current/public

RewriteCond %{DOCUMENT_ROOT}/system/maintenance.html -f
RewriteCond %{SCRIPT_FILENAME} !maintenance.html
RewriteRule ^.*$ %{DOCUMENT_ROOT}/system/maintenance.html [L]

RewriteCond %{REQUEST_FILENAME} -f
RewriteRule ^(.*)$ $1 [QSA,L]

RewriteCond %{REQUEST_FILENAME}/index.html -f
RewriteRule ^(.*)$ $1/index.html [QSA,L]

RewriteCond %{REQUEST_FILENAME}.html -f
RewriteRule ^(.*)$ $1.html [QSA,L]

RewriteRule ^/(.*)$ balancer://mongrel_cluster%{REQUEST_URI} [P,QSA,L]

should be converted to

location / {
root /var/www/myapp.com/current/public;

try_files /system/maintenance.html
$uri $uri/index.html $uri.html
@mongrel;
}

location @mongrel {
proxy_pass http://mongrel;
}
Module ngx_http_access_module

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Module ngx_http_access_module

Example Configuration
Directives
allow
deny

The ngx_http_access_module module allows
limiting access to certain client addresses.

Access can also be limited by
password, by the
result of subrequest,
or by JWT.
Simultaneous limitation of access by address and by password is controlled
by the satisfy directive.

Example Configuration

location / {
deny 192.168.1.1;
allow 192.168.1.0/24;
allow 10.1.1.0/16;
allow 2001:0db8::/32;
deny all;
}

The rules are checked in sequence until the first match is found.
In this example, access is allowed only for IPv4 networks
10.1.1.0/16 and 192.168.1.0/24
excluding the address 192.168.1.1,
and for IPv6 network 2001:0db8::/32.
In case of a lot of rules, the use of the
ngx_http_geo_module
module variables is preferable.

Directives

Syntax:

allow
address |
CIDR |
unix: |
all;

Default:

—

Context:

http, server, location, limit_except

Allows access for the specified network or address.
If the special value unix: is specified (1.5.1),
allows access for all UNIX-domain sockets.

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

Syntax:

deny
address |
CIDR |
unix: |
all;

Default:

—

Context:

http, server, location, limit_except

Denies access for the specified network or address.
If the special value unix: is specified (1.5.1),
denies access for all UNIX-domain sockets.

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

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Module ngx_http_addition_module

Example Configuration
Directives
add_before_body
add_after_body
addition_types

The ngx_http_addition_module module is a filter
that adds text before and after a response.
This module is not built by default, it should be enabled with the
--with-http_addition_module
configuration parameter.

Example Configuration

location / {
add_before_body /before_action;
add_after_body /after_action;
}

Directives

Syntax:

add_before_body uri;

Default:

—

Context:

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.

Syntax:

add_after_body uri;

Default:

—

Context:

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.

Syntax:

addition_types mime-type ...;

Default:

addition_types text/html;

Context:

http, server, location

This directive appeared in version 0.7.9.

Allows adding text in responses with the specified MIME types,
in addition to “text/html”.
The special value “*” matches any MIME type (0.8.29).
Module ngx_http_auth_basic_module

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Module ngx_http_auth_basic_module

Example Configuration
Directives
auth_basic
auth_basic_user_file

The ngx_http_auth_basic_module module 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, by the
result of subrequest,
or by JWT.
Simultaneous limitation of access by address and by password is controlled
by the satisfy directive.

Example Configuration

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

Directives

Syntax:

auth_basic string | off;

Default:

auth_basic off;

Context:

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 (1.3.10, 1.2.7).
The special value off cancels the effect
of the auth_basic directive
inherited from the previous configuration level.

Syntax:

auth_basic_user_file file;

Default:

—

Context:

http, server, location, limit_except

Specifies a file that keeps user names and passwords,
in the following format:

# 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 (1.0.3+) as described in
RFC 2307;
currently implemented schemes include PLAIN (an example one,
should not be used), SHA (1.3.13) (plain SHA-1
hashing, should not be used) and SSHA (salted SHA-1 hashing,
used by some software packages, notably OpenLDAP and Dovecot).

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
attacks.
Module ngx_http_auth_request_module

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Module ngx_http_auth_request_module

Example Configuration
Directives
auth_request
auth_request_set

The ngx_http_auth_request_module module (1.5.4+) 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.

This module is not built by default, it should be enabled with the
--with-http_auth_request_module
configuration parameter.

The module may be combined with
other access modules, such as
ngx_http_access_module,
ngx_http_auth_basic_module,
and
ngx_http_auth_jwt_module,
via the satisfy directive.

Before version 1.7.3, responses to authorization subrequests could not be cached
(using proxy_cache,
proxy_store, etc.).

Example Configuration

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

Syntax:

auth_request uri | off;

Default:

auth_request off;

Context:

http, server, location

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

Syntax:

auth_request_set $variable value;

Default:

—

Context:

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_*.
Module ngx_http_auth_require_module

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Module ngx_http_auth_require_module

Example Configuration
Directives
auth_require

The ngx_http_auth_require_module module (1.29.0)
implements variable-based client authorization.
It can also use variables
provided by other access modules such as
ngx_http_auth_request_module
or
ngx_http_auth_oidc_module.

This module is available as part of our
commercial subscription.

Example Configuration

http {
oidc_provider my_idp {
...
}

map $oidc_claim_role $admin_role {
"admin" 1;
}

server {
auth_oidc my_idp;

location /admin {
auth_require $admin_role;
}
}
}

Directives

Syntax:

auth_require
$value ...
[error=4xx |
5xx]
;

Default:

auth_require off;

Context:

http, server, location, limit_except

Enables authorization based on the specified variables.
The access is allowed only if all the variables are not
empty and are not equal to “0”.
Otherwise, the module returns 403 code, which can be
overridden by the error parameter.
Several auth_require directives can be used to return
different error codes.
Module ngx_http_autoindex_module

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Module ngx_http_autoindex_module

Example Configuration
Directives
autoindex
autoindex_exact_size
autoindex_format
autoindex_localtime

The ngx_http_autoindex_module module processes requests
ending with the slash character (‘/’) and produces
a directory listing.
Usually a request is passed to the ngx_http_autoindex_module
module when the
ngx_http_index_module module
cannot find an index file.

Example Configuration

location / {
autoindex on;
}

Directives

Syntax:

autoindex on | off;

Default:

autoindex off;

Context:

http, server, location

Enables or disables the directory listing output.

Syntax:

autoindex_exact_size on | off;

Default:

autoindex_exact_size on;

Context:

http, server, location

For the HTML format,
specifies whether exact file sizes should be output in the directory listing,
or rather rounded to kilobytes, megabytes, and gigabytes.

Syntax:

autoindex_format
html |
xml |
json |
jsonp;

Default:

autoindex_format html;

Context:

http, server, location

This directive appeared in version 1.7.9.

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
ngx_http_xslt_module module.

Syntax:

autoindex_localtime on | off;

Default:

autoindex_localtime off;

Context:

http, server, location

For the HTML format,
specifies whether times in the directory listing should be
output in the local time zone or UTC.
Module ngx_http_browser_module

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Module ngx_http_browser_module

Example Configuration
Directives
ancient_browser
ancient_browser_value
modern_browser
modern_browser_value

The ngx_http_browser_module module creates variables
whose values depend on the value of the “User-Agent”
request header field:

$modern_browser

equals the value set by the modern_browser_value directive,
if a browser was identified as modern;

$ancient_browser

equals the value set by the ancient_browser_value directive,
if a browser was identified as ancient;

$msie

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

Example Configuration

Choosing an index file:

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:

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

Syntax:

ancient_browser string ...;

Default:

—

Context:

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]”.

Syntax:

ancient_browser_value string;

Default:

ancient_browser_value 1;

Context:

http, server, location

Sets a value for the $ancient_browser variables.

Syntax:

modern_browser browser version;
modern_browser unlisted;

Default:

—

Context:

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 format 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
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.

Syntax:

modern_browser_value string;

Default:

modern_browser_value 1;

Context:

http, server, location

Sets a value for the $modern_browser variables.
Module ngx_http_dav_module

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Module ngx_http_dav_module

Example Configuration
Directives
create_full_put_path
dav_access
dav_methods
min_delete_depth

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

This module is not built by default, it should be enabled with the
--with-http_dav_module
configuration parameter.

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

Example Configuration

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

Syntax:

create_full_put_path on | off;

Default:

create_full_put_path off;

Context:

http, server, location

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

Syntax:

dav_access users:permissions ...;

Default:

dav_access user:rw;

Context:

http, server, location

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

dav_access user:rw group:rw all:r;

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

dav_access group:rw all:r;

Syntax:

dav_methods
off | method ...;

Default:

dav_methods off;

Context:

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
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.

Syntax:

min_delete_depth number;

Default:

min_delete_depth 0;

Context:

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

min_delete_depth 4;

allows removing files on requests

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

and denies the removal of

/users/00/00
Module ngx_http_empty_gif_module

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Module ngx_http_empty_gif_module

Example Configuration
Directives
empty_gif

The ngx_http_empty_gif_module module emits
single-pixel transparent GIF.

Example Configuration

location = /_.gif {
empty_gif;
}

Directives

Syntax:

empty_gif;

Default:

—

Context:

location

Turns on module processing in a surrounding location.