<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Alphabetical index of directives</title><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="../../css/style_en.css">

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

<input class="side-menu" type="checkbox" id="side-menu">

english

русский

news

about

download

security

documentation

faq

books

community

enterprise

community forum (new)

x.com

blog

njs

ingress controller

gateway fabric

Alphabetical index of directives

      absolute_redirect
accept_mutex
accept_mutex_delay
accept_terms_of_service
access_log (ngx_http_log_module)
access_log (ngx_stream_log_module)
account_key
acme_certificate
acme_issuer
acme_shared_zone
add_after_body
add_before_body
add_header
add_header_inherit
add_trailer
add_trailer_inherit
addition_types
aio
aio_write
alias
allow (ngx_http_access_module)
allow (ngx_stream_access_module)
ancient_browser
ancient_browser_value
api
auth_basic
auth_basic_user_file
auth_delay
auth_http
auth_http_header
auth_http_pass_client_cert
auth_http_timeout
auth_jwt
auth_jwt_claim_set
auth_jwt_header_set
auth_jwt_key_cache
auth_jwt_key_file
auth_jwt_key_request
auth_jwt_leeway
auth_jwt_require
auth_jwt_type
auth_oidc
auth_request
auth_request_set
auth_require
autoindex
autoindex_exact_size
autoindex_format
autoindex_localtime
break
challenge
charset
charset_map
charset_types
chunked_transfer_encoding
client_body_buffer_size
client_body_in_file_only
client_body_in_single_buffer
client_body_temp_path
client_body_timeout
client_header_buffer_size
client_header_timeout
client_id
client_max_body_size
client_secret
common_name_in_csr
config_url
connection_pool_size
contact
cookie_name
create_full_put_path
daemon
dav_access
dav_methods
debug_connection
debug_points
default_type
deny (ngx_http_access_module)
deny (ngx_stream_access_module)
directio
directio_alignment
disable_symlinks
early_hints
empty_gif
enforce_initial_report
env
error_log
error_log_tag
error_page
etag
events
expires
external_account_key
extra_auth_args
f4f
f4f_buffer_size
fastcgi_allow_upstream
fastcgi_bind
fastcgi_bind_dynamic
fastcgi_buffer_size
fastcgi_buffering
fastcgi_buffers
fastcgi_busy_buffers_size
fastcgi_cache
fastcgi_cache_background_update
fastcgi_cache_bypass
fastcgi_cache_key
fastcgi_cache_lock
fastcgi_cache_lock_age
fastcgi_cache_lock_timeout
fastcgi_cache_max_range_offset
fastcgi_cache_methods
fastcgi_cache_min_uses
fastcgi_cache_path
fastcgi_cache_purge
fastcgi_cache_revalidate
fastcgi_cache_use_stale
fastcgi_cache_valid
fastcgi_catch_stderr
fastcgi_connect_timeout
fastcgi_force_ranges
fastcgi_hide_header
fastcgi_ignore_client_abort
fastcgi_ignore_headers
fastcgi_index
fastcgi_intercept_errors
fastcgi_keep_conn
fastcgi_limit_rate
fastcgi_max_temp_file_size
fastcgi_next_upstream
fastcgi_next_upstream_timeout
fastcgi_next_upstream_tries
fastcgi_no_cache
fastcgi_param
fastcgi_pass
fastcgi_pass_header
fastcgi_pass_request_body
fastcgi_pass_request_headers
fastcgi_read_timeout
fastcgi_request_buffering
fastcgi_request_dynamic
fastcgi_send_lowat
fastcgi_send_timeout
fastcgi_socket_keepalive
fastcgi_split_path_info
fastcgi_store
fastcgi_store_access
fastcgi_temp_file_write_size
fastcgi_temp_path
flv
frontchannel_logout_uri
geo (ngx_http_geo_module)
geo (ngx_stream_geo_module)
geoip_city (ngx_http_geoip_module)
geoip_city (ngx_stream_geoip_module)
geoip_country (ngx_http_geoip_module)
geoip_country (ngx_stream_geoip_module)
geoip_org (ngx_http_geoip_module)
geoip_org (ngx_stream_geoip_module)
geoip_proxy
geoip_proxy_recursive
google_perftools_profiles
grpc_allow_upstream
grpc_bind
grpc_bind_dynamic
grpc_buffer_size
grpc_connect_timeout
grpc_hide_header
grpc_ignore_headers
grpc_intercept_errors
grpc_next_upstream
grpc_next_upstream_timeout
grpc_next_upstream_tries
grpc_pass
grpc_pass_header
grpc_read_timeout
grpc_request_dynamic
grpc_send_timeout
grpc_set_header
grpc_socket_keepalive
grpc_ssl_certificate
grpc_ssl_certificate_cache
grpc_ssl_certificate_key
grpc_ssl_ciphers
grpc_ssl_conf_command
grpc_ssl_crl
grpc_ssl_key_log
grpc_ssl_name
grpc_ssl_password_file
grpc_ssl_protocols
grpc_ssl_server_name
grpc_ssl_session_reuse
grpc_ssl_trusted_certificate
grpc_ssl_verify
grpc_ssl_verify_depth
gunzip
gunzip_buffers
gzip
gzip_buffers
gzip_comp_level
gzip_disable
gzip_http_version
gzip_min_length
gzip_proxied
gzip_static
gzip_types
gzip_vary
hash (ngx_http_upstream_module)
hash (ngx_stream_upstream_module)
health_check (ngx_http_upstream_hc_module)
health_check (ngx_stream_upstream_hc_module)
health_check_timeout
hls
hls_buffers
hls_forward_args
hls_fragment
hls_mp4_buffer_size
hls_mp4_max_buffer_size
http
http2
http2_body_preread_size
http2_chunk_size
http2_idle_timeout
http2_max_concurrent_pushes
http2_max_concurrent_streams
http2_max_field_size
http2_max_header_size
http2_max_requests
http2_push
http2_push_preload
http2_recv_buffer_size
http2_recv_timeout
http3
http3_hq
http3_max_concurrent_streams
http3_stream_buffer_size
if
if_modified_since
ignore_invalid_headers
image_filter
image_filter_buffer
image_filter_interlace
image_filter_jpeg_quality
image_filter_sharpen
image_filter_transparency
image_filter_webp_quality
imap_auth
imap_capabilities
imap_client_buffer
include
index
internal
internal_redirect
ip_hash
issuer
js_access (ngx_http_js_module)
js_access (ngx_stream_js_module)
js_body_filter
js_content
js_context_reuse (ngx_http_js_module)
js_context_reuse (ngx_stream_js_module)
js_engine (ngx_http_js_module)
js_engine (ngx_stream_js_module)
js_fetch_buffer_size (ngx_http_js_module)
js_fetch_buffer_size (ngx_stream_js_module)
js_fetch_ciphers (ngx_http_js_module)
js_fetch_ciphers (ngx_stream_js_module)
js_fetch_keepalive (ngx_http_js_module)
js_fetch_keepalive (ngx_stream_js_module)
js_fetch_keepalive_requests (ngx_http_js_module)
js_fetch_keepalive_requests (ngx_stream_js_module)
js_fetch_keepalive_time (ngx_http_js_module)
js_fetch_keepalive_time (ngx_stream_js_module)
js_fetch_keepalive_timeout (ngx_http_js_module)
js_fetch_keepalive_timeout (ngx_stream_js_module)
js_fetch_max_response_buffer_size (ngx_http_js_module)
js_fetch_max_response_buffer_size (ngx_stream_js_module)
js_fetch_protocols (ngx_http_js_module)
js_fetch_protocols (ngx_stream_js_module)
js_fetch_proxy (ngx_http_js_module)
js_fetch_proxy (ngx_stream_js_module)
js_fetch_timeout (ngx_http_js_module)
js_fetch_timeout (ngx_stream_js_module)
js_fetch_trusted_certificate (ngx_http_js_module)
js_fetch_trusted_certificate (ngx_stream_js_module)
js_fetch_verify (ngx_http_js_module)
js_fetch_verify (ngx_stream_js_module)
js_fetch_verify_depth (ngx_http_js_module)
js_fetch_verify_depth (ngx_stream_js_module)
js_filter
js_header_filter
js_import (ngx_http_js_module)
js_import (ngx_stream_js_module)
js_include (ngx_http_js_module)
js_include (ngx_stream_js_module)
js_load_http_native_module
js_load_stream_native_module
js_path (ngx_http_js_module)
js_path (ngx_stream_js_module)
js_periodic (ngx_http_js_module)
js_periodic (ngx_stream_js_module)
js_preload_object (ngx_http_js_module)
js_preload_object (ngx_stream_js_module)
js_preread
js_set (ngx_http_js_module)
js_set (ngx_stream_js_module)
js_shared_dict_zone (ngx_http_js_module)
js_shared_dict_zone (ngx_stream_js_module)
js_var (ngx_http_js_module)
js_var (ngx_stream_js_module)
keepalive
keepalive_disable
keepalive_min_timeout
keepalive_requests (ngx_http_core_module)
keepalive_requests (ngx_http_upstream_module)
keepalive_time (ngx_http_core_module)
keepalive_time (ngx_http_upstream_module)
keepalive_timeout (ngx_http_core_module)
keepalive_timeout (ngx_http_upstream_module)
keyval (ngx_http_keyval_module)
keyval (ngx_stream_keyval_module)
keyval_zone (ngx_http_keyval_module)
keyval_zone (ngx_stream_keyval_module)
large_client_header_buffers
least_conn (ngx_http_upstream_module)
least_conn (ngx_stream_upstream_module)
least_time (ngx_http_upstream_module)
least_time (ngx_stream_upstream_module)
license_token
limit_conn (ngx_http_limit_conn_module)
limit_conn (ngx_stream_limit_conn_module)
limit_conn_dry_run (ngx_http_limit_conn_module)
limit_conn_dry_run (ngx_stream_limit_conn_module)
limit_conn_log_level (ngx_http_limit_conn_module)
limit_conn_log_level (ngx_stream_limit_conn_module)
limit_conn_status
limit_conn_zone (ngx_http_limit_conn_module)
limit_conn_zone (ngx_stream_limit_conn_module)
limit_except
limit_rate
limit_rate_after
limit_req
limit_req_dry_run
limit_req_log_level
limit_req_status
limit_req_zone
limit_zone
lingering_close
lingering_time
lingering_timeout
listen (ngx_http_core_module)
listen (ngx_mail_core_module)
listen (ngx_stream_core_module)
load_module
location
lock_file
log_format (ngx_http_log_module)
log_format (ngx_stream_log_module)
log_not_found
log_subrequest
logout_token_hint
logout_uri
mail
map (ngx_http_map_module)
map (ngx_stream_map_module)
map_hash_bucket_size (ngx_http_map_module)
map_hash_bucket_size (ngx_stream_map_module)
map_hash_max_size (ngx_http_map_module)
map_hash_max_size (ngx_stream_map_module)
master_process
match (ngx_http_upstream_hc_module)
match (ngx_stream_upstream_hc_module)
max_errors
max_headers
max_ranges
memcached_allow_upstream
memcached_bind
memcached_bind_dynamic
memcached_buffer_size
memcached_connect_timeout
memcached_gzip_flag
memcached_next_upstream
memcached_next_upstream_timeout
memcached_next_upstream_tries
memcached_pass
memcached_read_timeout
memcached_send_timeout
memcached_socket_keepalive
merge_slashes
mgmt
min_delete_depth
mirror
mirror_request_body
modern_browser
modern_browser_value
mp4
mp4_buffer_size
mp4_limit_rate
mp4_limit_rate_after
mp4_max_buffer_size
mp4_start_key_frame
mqtt
mqtt_buffers
mqtt_preread
mqtt_rewrite_buffer_size
mqtt_set_connect
msie_padding
msie_refresh
multi_accept
ntlm
num_map (ngx_http_num_map_module)
num_map (ngx_stream_num_map_module)
oidc_provider
open_file_cache
open_file_cache_errors
open_file_cache_min_uses
open_file_cache_valid
open_log_file_cache (ngx_http_log_module)
open_log_file_cache (ngx_stream_log_module)
otel_exporter
otel_resource_attr
otel_service_name
otel_span_attr
otel_span_name
otel_trace
otel_trace_context
output_buffers
override_charset
pass
pcre_jit
perl
perl_modules
perl_require
perl_set
pid
pkce
pop3_auth
pop3_capabilities
port_in_redirect
post_logout_uri
postpone_output
preferred_chain
preread_buffer_size
preread_timeout
profile
protocol
proxy
proxy_allow_upstream
proxy_bind (ngx_http_proxy_module)
proxy_bind (ngx_stream_proxy_module)
proxy_bind_dynamic (ngx_http_proxy_module)
proxy_bind_dynamic (ngx_stream_proxy_module)
proxy_buffer
proxy_buffer_size (ngx_http_proxy_module)
proxy_buffer_size (ngx_stream_proxy_module)
proxy_buffering
proxy_buffers
proxy_busy_buffers_size
proxy_cache
proxy_cache_background_update
proxy_cache_bypass
proxy_cache_convert_head
proxy_cache_key
proxy_cache_lock
proxy_cache_lock_age
proxy_cache_lock_timeout
proxy_cache_max_range_offset
proxy_cache_methods
proxy_cache_min_uses
proxy_cache_path
proxy_cache_purge
proxy_cache_revalidate
proxy_cache_use_stale
proxy_cache_valid
proxy_connect_timeout (ngx_http_proxy_module)
proxy_connect_timeout (ngx_stream_proxy_module)
proxy_cookie_domain
proxy_cookie_flags
proxy_cookie_path
proxy_download_rate
proxy_force_ranges
proxy_half_close
proxy_headers_hash_bucket_size
proxy_headers_hash_max_size
proxy_hide_header
proxy_http_version
proxy_ignore_client_abort
proxy_ignore_headers
proxy_intercept_errors
proxy_limit_rate
proxy_max_temp_file_size
proxy_method
proxy_next_upstream (ngx_http_proxy_module)
proxy_next_upstream (ngx_stream_proxy_module)
proxy_next_upstream_timeout (ngx_http_proxy_module)
proxy_next_upstream_timeout (ngx_stream_proxy_module)
proxy_next_upstream_tries (ngx_http_proxy_module)
proxy_next_upstream_tries (ngx_stream_proxy_module)
proxy_no_cache
proxy_pass (ngx_http_proxy_module)
proxy_pass (ngx_stream_proxy_module)
proxy_pass_error_message
proxy_pass_header
proxy_pass_request_body
proxy_pass_request_headers
proxy_pass_trailers
proxy_password
proxy_protocol (ngx_mail_proxy_module)
proxy_protocol (ngx_stream_proxy_module)
proxy_protocol_timeout
proxy_read_timeout
proxy_redirect
proxy_request_buffering
proxy_request_dynamic
proxy_requests
proxy_responses
proxy_send_lowat
proxy_send_timeout
proxy_session_drop
proxy_set_body
proxy_set_header
proxy_smtp_auth
proxy_socket_keepalive (ngx_http_proxy_module)
proxy_socket_keepalive (ngx_stream_proxy_module)
proxy_ssl
proxy_ssl_alpn
proxy_ssl_certificate (ngx_http_proxy_module)
proxy_ssl_certificate (ngx_stream_proxy_module)
proxy_ssl_certificate_cache (ngx_http_proxy_module)
proxy_ssl_certificate_cache (ngx_stream_proxy_module)
proxy_ssl_certificate_key (ngx_http_proxy_module)
proxy_ssl_certificate_key (ngx_stream_proxy_module)
proxy_ssl_ciphers (ngx_http_proxy_module)
proxy_ssl_ciphers (ngx_stream_proxy_module)
proxy_ssl_conf_command (ngx_http_proxy_module)
proxy_ssl_conf_command (ngx_stream_proxy_module)
proxy_ssl_crl (ngx_http_proxy_module)
proxy_ssl_crl (ngx_stream_proxy_module)
proxy_ssl_key_log (ngx_http_proxy_module)
proxy_ssl_key_log (ngx_stream_proxy_module)
proxy_ssl_name (ngx_http_proxy_module)
proxy_ssl_name (ngx_stream_proxy_module)
proxy_ssl_password_file (ngx_http_proxy_module)
proxy_ssl_password_file (ngx_stream_proxy_module)
proxy_ssl_protocols (ngx_http_proxy_module)
proxy_ssl_protocols (ngx_stream_proxy_module)
proxy_ssl_server_name (ngx_http_proxy_module)
proxy_ssl_server_name (ngx_stream_proxy_module)
proxy_ssl_session_reuse (ngx_http_proxy_module)
proxy_ssl_session_reuse (ngx_stream_proxy_module)
proxy_ssl_trusted_certificate (ngx_http_proxy_module)
proxy_ssl_trusted_certificate (ngx_stream_proxy_module)
proxy_ssl_verify (ngx_http_proxy_module)
proxy_ssl_verify (ngx_stream_proxy_module)
proxy_ssl_verify_depth (ngx_http_proxy_module)
proxy_ssl_verify_depth (ngx_stream_proxy_module)
proxy_store
proxy_store_access
proxy_temp_file_write_size
proxy_temp_path
proxy_timeout (ngx_mail_proxy_module)
proxy_timeout (ngx_stream_proxy_module)
proxy_upload_rate
proxy_username
queue
quic_active_connection_id_limit
quic_bpf
quic_gso
quic_host_key
quic_retry
random (ngx_http_upstream_module)
random (ngx_stream_upstream_module)
random_index
read_ahead
real_ip_header
real_ip_recursive
recursive_error_pages
redirect_uri
referer_hash_bucket_size
referer_hash_max_size
request_pool_size
reset_timedout_connection
resolver (ngx_http_core_module)
resolver (ngx_http_upstream_module)
resolver (ngx_mail_core_module)
resolver (ngx_stream_core_module)
resolver (ngx_stream_upstream_module)
resolver (ngx_mgmt_module)
resolver_timeout (ngx_http_core_module)
resolver_timeout (ngx_http_upstream_module)
resolver_timeout (ngx_mail_core_module)
resolver_timeout (ngx_stream_core_module)
resolver_timeout (ngx_stream_upstream_module)
return (ngx_http_rewrite_module)
return (ngx_stream_return_module)
rewrite
rewrite_log
root
satisfy
scgi_allow_upstream
scgi_bind
scgi_bind_dynamic
scgi_buffer_size
scgi_buffering
scgi_buffers
scgi_busy_buffers_size
scgi_cache
scgi_cache_background_update
scgi_cache_bypass
scgi_cache_key
scgi_cache_lock
scgi_cache_lock_age
scgi_cache_lock_timeout
scgi_cache_max_range_offset
scgi_cache_methods
scgi_cache_min_uses
scgi_cache_path
scgi_cache_purge
scgi_cache_revalidate
scgi_cache_use_stale
scgi_cache_valid
scgi_connect_timeout
scgi_force_ranges
scgi_hide_header
scgi_ignore_client_abort
scgi_ignore_headers
scgi_intercept_errors
scgi_limit_rate
scgi_max_temp_file_size
scgi_next_upstream
scgi_next_upstream_timeout
scgi_next_upstream_tries
scgi_no_cache
scgi_param
scgi_pass
scgi_pass_header
scgi_pass_request_body
scgi_pass_request_headers
scgi_read_timeout
scgi_request_buffering
scgi_request_dynamic
scgi_send_timeout
scgi_socket_keepalive
scgi_store
scgi_store_access
scgi_temp_file_write_size
scgi_temp_path
scope
secure_link
secure_link_md5
secure_link_secret
send_lowat
send_timeout
sendfile
sendfile_max_chunk
server (ngx_http_core_module)
server (ngx_http_upstream_module)
server (ngx_mail_core_module)
server (ngx_stream_core_module)
server (ngx_stream_upstream_module)
server_name (ngx_http_core_module)
server_name (ngx_mail_core_module)
server_name (ngx_stream_core_module)
server_name_in_redirect
server_names_hash_bucket_size (ngx_http_core_module)
server_names_hash_bucket_size (ngx_stream_core_module)
server_names_hash_max_size (ngx_http_core_module)
server_names_hash_max_size (ngx_stream_core_module)
server_tokens
session_log
session_log_format
session_log_zone
session_store
session_timeout
set (ngx_http_rewrite_module)
set (ngx_stream_set_module)
set_real_ip_from (ngx_http_realip_module)
set_real_ip_from (ngx_mail_realip_module)
set_real_ip_from (ngx_stream_realip_module)
slice
smtp_auth
smtp_capabilities
smtp_client_buffer
smtp_greeting_delay
source_charset
split_clients (ngx_http_split_clients_module)
split_clients (ngx_stream_split_clients_module)
ssi
ssi_last_modified
ssi_min_file_chunk
ssi_silent_errors
ssi_types
ssi_value_length
ssl (ngx_http_ssl_module)
ssl (ngx_mail_ssl_module)
ssl_alpn
ssl_buffer_size
ssl_certificate (ngx_http_ssl_module)
ssl_certificate (ngx_mail_ssl_module)
ssl_certificate (ngx_stream_ssl_module)
ssl_certificate_cache (ngx_http_ssl_module)
ssl_certificate_cache (ngx_stream_ssl_module)
ssl_certificate_compression (ngx_http_ssl_module)
ssl_certificate_compression (ngx_mail_ssl_module)
ssl_certificate_compression (ngx_stream_ssl_module)
ssl_certificate_key (ngx_http_ssl_module)
ssl_certificate_key (ngx_mail_ssl_module)
ssl_certificate_key (ngx_stream_ssl_module)
ssl_ciphers (ngx_http_ssl_module)
ssl_ciphers (ngx_mail_ssl_module)
ssl_ciphers (ngx_stream_ssl_module)
ssl_client_certificate (ngx_http_ssl_module)
ssl_client_certificate (ngx_mail_ssl_module)
ssl_client_certificate (ngx_stream_ssl_module)
ssl_conf_command (ngx_http_ssl_module)
ssl_conf_command (ngx_mail_ssl_module)
ssl_conf_command (ngx_stream_ssl_module)
ssl_crl (ngx_http_oidc_module)
ssl_crl (ngx_http_ssl_module)
ssl_crl (ngx_mail_ssl_module)
ssl_crl (ngx_stream_ssl_module)
ssl_crl (ngx_mgmt_module)
ssl_dhparam (ngx_http_ssl_module)
ssl_dhparam (ngx_mail_ssl_module)
ssl_dhparam (ngx_stream_ssl_module)
ssl_early_data
ssl_ecdh_curve (ngx_http_ssl_module)
ssl_ecdh_curve (ngx_mail_ssl_module)
ssl_ecdh_curve (ngx_stream_ssl_module)
ssl_ech_file (ngx_http_ssl_module)
ssl_ech_file (ngx_stream_ssl_module)
ssl_engine
ssl_handshake_timeout
ssl_key_log (ngx_http_ssl_module)
ssl_key_log (ngx_stream_ssl_module)
ssl_object_cache_inheritable
ssl_ocsp (ngx_http_ssl_module)
ssl_ocsp (ngx_stream_ssl_module)
ssl_ocsp_cache (ngx_http_ssl_module)
ssl_ocsp_cache (ngx_stream_ssl_module)
ssl_ocsp_responder (ngx_http_ssl_module)
ssl_ocsp_responder (ngx_stream_ssl_module)
ssl_password_file (ngx_http_ssl_module)
ssl_password_file (ngx_mail_ssl_module)
ssl_password_file (ngx_stream_ssl_module)
ssl_prefer_server_ciphers (ngx_http_ssl_module)
ssl_prefer_server_ciphers (ngx_mail_ssl_module)
ssl_prefer_server_ciphers (ngx_stream_ssl_module)
ssl_preread
ssl_protocols (ngx_http_ssl_module)
ssl_protocols (ngx_mail_ssl_module)
ssl_protocols (ngx_stream_ssl_module)
ssl_reject_handshake (ngx_http_ssl_module)
ssl_reject_handshake (ngx_stream_ssl_module)
ssl_session_cache (ngx_http_ssl_module)
ssl_session_cache (ngx_mail_ssl_module)
ssl_session_cache (ngx_stream_ssl_module)
ssl_session_ticket_key (ngx_http_ssl_module)
ssl_session_ticket_key (ngx_mail_ssl_module)
ssl_session_ticket_key (ngx_stream_ssl_module)
ssl_session_tickets (ngx_http_ssl_module)
ssl_session_tickets (ngx_mail_ssl_module)
ssl_session_tickets (ngx_stream_ssl_module)
ssl_session_timeout (ngx_http_ssl_module)
ssl_session_timeout (ngx_mail_ssl_module)
ssl_session_timeout (ngx_stream_ssl_module)
ssl_stapling (ngx_http_ssl_module)
ssl_stapling (ngx_stream_ssl_module)
ssl_stapling_file (ngx_http_ssl_module)
ssl_stapling_file (ngx_stream_ssl_module)
ssl_stapling_responder (ngx_http_ssl_module)
ssl_stapling_responder (ngx_stream_ssl_module)
ssl_stapling_verify (ngx_http_ssl_module)
ssl_stapling_verify (ngx_stream_ssl_module)
ssl_trusted_certificate (ngx_http_oidc_module)
ssl_trusted_certificate (ngx_http_ssl_module)
ssl_trusted_certificate (ngx_http_acme_module)
ssl_trusted_certificate (ngx_mail_ssl_module)
ssl_trusted_certificate (ngx_stream_ssl_module)
ssl_trusted_certificate (ngx_mgmt_module)
ssl_verify (ngx_http_acme_module)
ssl_verify (ngx_mgmt_module)
ssl_verify_client (ngx_http_ssl_module)
ssl_verify_client (ngx_mail_ssl_module)
ssl_verify_client (ngx_stream_ssl_module)
ssl_verify_depth (ngx_http_ssl_module)
ssl_verify_depth (ngx_mail_ssl_module)
ssl_verify_depth (ngx_stream_ssl_module)
stall_threshold
starttls
state (ngx_http_upstream_module)
state (ngx_stream_upstream_module)
state_path (ngx_http_acme_module)
state_path (ngx_mgmt_module)
status
status_format
status_zone (ngx_http_api_module)
status_zone (ngx_http_status_module)
sticky
stream
stub_status
sub_filter
sub_filter_last_modified
sub_filter_once
sub_filter_types
subrequest_output_buffer_size
tcp_nodelay (ngx_http_core_module)
tcp_nodelay (ngx_stream_core_module)
tcp_nopush
thread_pool
timeout
timer_resolution
try_files
tunnel_allow_upstream
tunnel_bind
tunnel_bind_dynamic
tunnel_buffer_size
tunnel_connect_timeout
tunnel_next_upstream
tunnel_next_upstream_timeout
tunnel_next_upstream_tries
tunnel_pass
tunnel_read_timeout
tunnel_send_lowat
tunnel_send_timeout
tunnel_socket_keepalive
types
types_hash_bucket_size
types_hash_max_size
underscores_in_headers
uninitialized_variable_warn
upstream (ngx_http_upstream_module)
upstream (ngx_stream_upstream_module)
upstream_conf
uri
usage_report
use
user
userid
userid_domain
userid_expires
userid_flags
userid_mark
userid_name
userid_p3p
userid_path
userid_service
userinfo
uwsgi_allow_upstream
uwsgi_bind
uwsgi_bind_dynamic
uwsgi_buffer_size
uwsgi_buffering
uwsgi_buffers
uwsgi_busy_buffers_size
uwsgi_cache
uwsgi_cache_background_update
uwsgi_cache_bypass
uwsgi_cache_key
uwsgi_cache_lock
uwsgi_cache_lock_age
uwsgi_cache_lock_timeout
uwsgi_cache_max_range_offset
uwsgi_cache_methods
uwsgi_cache_min_uses
uwsgi_cache_path
uwsgi_cache_purge
uwsgi_cache_revalidate
uwsgi_cache_use_stale
uwsgi_cache_valid
uwsgi_connect_timeout
uwsgi_force_ranges
uwsgi_hide_header
uwsgi_ignore_client_abort
uwsgi_ignore_headers
uwsgi_intercept_errors
uwsgi_limit_rate
uwsgi_max_temp_file_size
uwsgi_modifier1
uwsgi_modifier2
uwsgi_next_upstream
uwsgi_next_upstream_timeout
uwsgi_next_upstream_tries
uwsgi_no_cache
uwsgi_param
uwsgi_pass
uwsgi_pass_header
uwsgi_pass_request_body
uwsgi_pass_request_headers
uwsgi_read_timeout
uwsgi_request_buffering
uwsgi_request_dynamic
uwsgi_send_timeout
uwsgi_socket_keepalive
uwsgi_ssl_certificate
uwsgi_ssl_certificate_cache
uwsgi_ssl_certificate_key
uwsgi_ssl_ciphers
uwsgi_ssl_conf_command
uwsgi_ssl_crl
uwsgi_ssl_key_log
uwsgi_ssl_name
uwsgi_ssl_password_file
uwsgi_ssl_protocols
uwsgi_ssl_server_name
uwsgi_ssl_session_reuse
uwsgi_ssl_trusted_certificate
uwsgi_ssl_verify
uwsgi_ssl_verify_depth
uwsgi_store
uwsgi_store_access
uwsgi_temp_file_write_size
uwsgi_temp_path
valid_referers
variables_hash_bucket_size (ngx_http_core_module)
variables_hash_bucket_size (ngx_stream_core_module)
variables_hash_max_size (ngx_http_core_module)
variables_hash_max_size (ngx_stream_core_module)
worker_aio_requests
worker_connections
worker_cpu_affinity
worker_priority
worker_processes
worker_rlimit_core
worker_rlimit_nofile
worker_shutdown_timeout
working_directory
xclient
xml_entities
xslt_last_modified
xslt_param
xslt_string_param
xslt_stylesheet
xslt_types
zone (ngx_http_upstream_module)
zone (ngx_stream_upstream_module)
zone_sync
zone_sync_buffers
zone_sync_connect_retry_interval
zone_sync_connect_timeout
zone_sync_interval
zone_sync_recv_buffer_size
zone_sync_server
zone_sync_ssl
zone_sync_ssl_certificate
zone_sync_ssl_certificate_key
zone_sync_ssl_ciphers
zone_sync_ssl_conf_command
zone_sync_ssl_crl
zone_sync_ssl_name
zone_sync_ssl_password_file
zone_sync_ssl_protocols
zone_sync_ssl_server_name
zone_sync_ssl_trusted_certificate
zone_sync_ssl_verify
zone_sync_ssl_verify_depth
zone_sync_timeout


<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Connection processing methods</title><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="../../css/style_en.css">

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

<input class="side-menu" type="checkbox" id="side-menu">

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


<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>FAQ</title><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="../../css/style_en.css">

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

<input class="side-menu" type="checkbox" id="side-menu">

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 ”


<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Setting up hashes</title><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="../../css/style_en.css">

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

<input class="side-menu" type="checkbox" id="side-menu">

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.


<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Building nginx on the Win32 platform with Visual C</title><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="../../css/style_en.css">

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

<input class="side-menu" type="checkbox" id="side-menu">

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


<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>nginx documentation</title><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="../../css/style_en.css">

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

<input class="side-menu" type="checkbox" id="side-menu">

english

русский

news

about

download

security

documentation

faq

books

community

enterprise

community forum (new)

x.com

blog

njs

ingress controller

gateway fabric

nginx documentation

Introduction

Installing nginx

Building nginx from Sources

Beginner’s Guide

Admin’s Guide

Controlling nginx

Connection processing methods

Setting up hashes

A debugging log

Logging to syslog

Configuration file measurement units

Command-line parameters

nginx for Windows

Support for QUIC and HTTP/3

How nginx processes a request

Server names

Using nginx as HTTP load balancer

Configuring HTTPS servers

How nginx processes a TCP/UDP session

Scripting with njs

Chapter “nginx” in
“The Architecture of Open Source Applications”

How-To

Building nginx on the Win32 platform with Visual C

Installing NGINX Plus AMIs on Amazon EC2

Debugging nginx with DTrace pid provider

Converting rewrite rules

WebSocket proxying

Development

Contributing Changes

Development guide

Modules reference

Alphabetical index of directives

Alphabetical index of variables

Core functionality

ngx_http_core_module

ngx_http_access_module

ngx_http_addition_module

ngx_http_api_module

ngx_http_auth_basic_module

ngx_http_auth_jwt_module

ngx_http_auth_request_module

ngx_http_auth_require_module

ngx_http_autoindex_module

ngx_http_browser_module

ngx_http_charset_module

ngx_http_dav_module

ngx_http_empty_gif_module

ngx_http_f4f_module

ngx_http_fastcgi_module

ngx_http_flv_module

ngx_http_geo_module

ngx_http_geoip_module

ngx_http_grpc_module

ngx_http_gunzip_module

ngx_http_gzip_module

ngx_http_gzip_static_module

ngx_http_headers_module

ngx_http_hls_module

ngx_http_image_filter_module

ngx_http_index_module

ngx_http_internal_redirect_module

ngx_http_js_module

ngx_http_keyval_module

ngx_http_limit_conn_module

ngx_http_limit_req_module

ngx_http_log_module

ngx_http_map_module

ngx_http_memcached_module

ngx_http_mirror_module

ngx_http_mp4_module

ngx_http_num_map_module

ngx_http_oidc_module

ngx_http_perl_module

ngx_http_proxy_module

ngx_http_proxy_protocol_vendor_module

ngx_http_random_index_module

ngx_http_realip_module

ngx_http_referer_module

ngx_http_rewrite_module

ngx_http_scgi_module

ngx_http_secure_link_module

ngx_http_session_log_module

ngx_http_slice_module

ngx_http_split_clients_module

ngx_http_ssi_module

ngx_http_ssl_module

ngx_http_status_module

ngx_http_stub_status_module

ngx_http_sub_module

ngx_http_tunnel_module

ngx_http_upstream_module

ngx_http_upstream_conf_module

ngx_http_upstream_hc_module

ngx_http_userid_module

ngx_http_uwsgi_module

ngx_http_v2_module

ngx_http_v3_module

ngx_http_xslt_module

ngx_mail_core_module

ngx_mail_auth_http_module

ngx_mail_proxy_module

ngx_mail_realip_module

ngx_mail_ssl_module

ngx_mail_imap_module

ngx_mail_pop3_module

ngx_mail_smtp_module

ngx_stream_core_module

ngx_stream_access_module

ngx_stream_geo_module

ngx_stream_geoip_module

ngx_stream_js_module

ngx_stream_keyval_module

ngx_stream_limit_conn_module

ngx_stream_log_module

ngx_stream_map_module

ngx_stream_mqtt_preread_module

ngx_stream_mqtt_filter_module

ngx_stream_num_map_module

ngx_stream_pass_module

ngx_stream_proxy_module

ngx_stream_proxy_protocol_vendor_module

ngx_stream_realip_module

ngx_stream_return_module

ngx_stream_set_module

ngx_stream_split_clients_module

ngx_stream_ssl_module

ngx_stream_ssl_preread_module

ngx_stream_upstream_module

ngx_stream_upstream_hc_module

ngx_stream_zone_sync_module

ngx_google_perftools_module

ngx_mgmt_module

ngx_http_acme_module

ngx_otel_module


<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Installing nginx</title><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="../../css/style_en.css">

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

<input class="side-menu" type="checkbox" id="side-menu">

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.


<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Debugging nginx with DTrace pid provider</title><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="../../css/style_en.css">

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

<input class="side-menu" type="checkbox" id="side-menu">

english

русский

news

about

download

security

documentation

faq

books

community

enterprise

community forum (new)

x.com

blog

njs

ingress controller

gateway fabric

Debugging nginx with DTrace pid provider

This article assumes the reader has a general knowledge of nginx internals and
DTrace.

Although nginx built with the --with-debug
option already provides a lot of information about request processing,
it is sometimes desirable to trace particular parts of code path more
thoroughly and at the same time omit the rest of debugging output.
DTrace pid provider (available on Solaris, macOS) is a useful tool to
explore userland program’s internals, since it doesn’t require any code
changes and it can help with the task.
A simple DTrace script to trace and print nginx function calls
may look like this:

#pragma D option flowindent

pid$target:nginx::entry {
}

pid$target:nginx::return {
}

DTrace capabilities for function calls tracing provide only a limited amount
of useful information, though.
Real-time inspection of function arguments is typically more interesting,
but also a bit more complicated.
Examples below are intended to help the reader become more familiar with
DTrace and the process of analyzing nginx behavior using DTrace.

One of the common scenarios for using DTrace with nginx is the following:
attach to the nginx worker process to log request lines and request start times.
The corresponding function to attach is
ngx_http_process_request(), and the argument in question
is a pointer to the ngx_http_request_t structure.
DTrace script for such request logging can be as simple as:

pid$target::*ngx_http_process_request:entry
{
    this->request = (ngx_http_request_t *)copyin(arg0, sizeof(ngx_http_request_t));
    this->request_line = stringof(copyin((uintptr_t)this->request->request_line.data,
                                         this->request->request_line.len));
    printf("request line = %s\n", this->request_line);
    printf("request start sec = %d\n", this->request->start_sec);
}

It should be noted that in the example above DTrace requires some knowledge
about the ngx_http_request_t structure.
Unfortunately while it is possible to use a specific #include
directive in the DTrace script and then pass it to a C preprocessor
(with the -C flag), that doesn’t really work.
Due to a lot of cross dependencies, almost all nginx header files
have to be included.
In turn, based on configure script settings,
nginx headers will include PCRE,
OpenSSL and a variety of system header files.
While in theory all those header files related to a specific nginx build
might be included in DTrace script preprocessing and compilation, in reality
DTrace script most probably will fail to compile because of unknown syntax in
some header files.

The problem above can be solved by including only the relevant and
necessary structure and type definitions in the DTrace script.
DTrace has to know sizes of structures, types, and fields offsets.
Thus dependencies can be further reduced by manually optimizing
structure definitions for use with DTrace.

Let’s use DTrace script example above and see what structure definitions
it needs to work properly.

First of all objs/ngx_auto_config.h file generated by
configure should be included, because it defines a number of constants
affecting various #ifdef’s.
After that, some basic types and definitions
like ngx_str_t, ngx_table_elt_t,
ngx_uint_t etc. should be put at the beginning of the
DTrace script.
These definitions are compact, commonly used and unlikely to be
frequently changed.

Then there’s the ngx_http_request_t structure that
contains a lot of pointers to other structures.
Because these pointers are really irrelevant to this script, and because they
have the same size, it is possible to just replace them with void pointers.
Instead of changing definitions, it is better to add appropriate typedefs,
though:

typedef ngx_http_upstream_t     void;
typedef ngx_http_request_body_t void;

Last but not least it is necessary to add definitions of two member structures
(ngx_http_headers_in_t,
ngx_http_headers_out_t),
declarations of callback functions and definitions of constants.

The final DTrace script can be downloaded from
here.

The following example shows the output of running this script:

# dtrace -C -I ./objs -s trace_process_request.d -p 4848
dtrace: script 'trace_process_request.d' matched 1 probe
CPU     ID                    FUNCTION:NAME
  1      4 .XAbmO.ngx_http_process_request:entry request line = GET / HTTP/1.1
request start sec = 1349162898

  0      4 .XAbmO.ngx_http_process_request:entry request line = GET /en/docs/nginx_dtrace_pid_provider.html HTTP/1.1
request start sec = 1349162899

Using similar techniques the reader should be able to trace other
nginx function calls.

See also

Solaris Dynamic Tracing Guide

Introduction article on DTrace pid provider


<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Core functionality</title><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="../../css/style_en.css">

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

<input class="side-menu" type="checkbox" id="side-menu">

english

русский

news

about

download

security

documentation

faq

books

community

enterprise

community forum (new)

x.com

blog

njs

ingress controller

gateway fabric

Core functionality

Example Configuration
Directives
     accept_mutex
     accept_mutex_delay
     daemon
     debug_connection
     debug_points
     env
     error_log
     events
     include
     load_module
     lock_file
     master_process
     multi_accept
     pcre_jit
     pid
     ssl_engine
     ssl_object_cache_inheritable
     stall_threshold
     thread_pool
     timer_resolution
     use
     user
     worker_aio_requests
     worker_connections
     worker_cpu_affinity
     worker_priority
     worker_processes
     worker_rlimit_core
     worker_rlimit_nofile
     worker_shutdown_timeout
     working_directory

Example Configuration

user www www;
worker_processes 2;

error_log /var/log/nginx-error.log info;

events {
    use kqueue;
    worker_connections 2048;
}

...

Directives

            Syntax:

            accept_mutex on | off;

            Default:

accept_mutex off;

            Context:

            events

If accept_mutex is enabled,
worker processes will accept new connections by turn.
Otherwise, all worker processes will be notified about new connections,
and if volume of new connections is low, some of the worker processes
may just waste system resources.

There is no need to enable accept_mutex
on systems that support the
EPOLLEXCLUSIVE flag (1.11.3) or
when using reuseport.

Prior to version 1.11.3, the default value was on.

            Syntax:

            accept_mutex_delay time;

            Default:

accept_mutex_delay 500ms;

            Context:

            events

If accept_mutex is enabled, specifies the maximum time
during which a worker process will try to restart accepting new
connections if another worker process is currently accepting
new connections.

            Syntax:

            daemon on | off;

            Default:

daemon on;

            Context:

            main

Determines whether nginx should become a daemon.
Mainly used during development.

            Syntax:

            debug_connection
    address |
    CIDR |
    unix:;

            Default:

            —

            Context:

            events

Enables debugging log for selected client connections.
Other connections will use logging level set by the
error_log directive.
Debugged connections are specified by IPv4 or IPv6 (1.3.0, 1.2.1)
address or network.
A connection may also be specified using a hostname.
For connections using UNIX-domain sockets (1.3.0, 1.2.1),
debugging log is enabled by the “unix:” parameter.

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:;
    ...
}

For this directive to work, nginx needs to
be built with --with-debug,
see “A debugging log”.

            Syntax:

            debug_points abort | stop;

            Default:

            —

            Context:

            main

This directive is used for debugging.

When internal error is detected, e.g. the leak of sockets on
restart of working processes, enabling debug_points
leads to a core file creation (abort)
or to stopping of a process (stop) for further
analysis using a system debugger.

            Syntax:

            env variable[=value];

            Default:

env TZ;

            Context:

            main

By default, nginx removes all environment variables inherited
from its parent process except the TZ variable.
This directive allows preserving some of the inherited variables,
changing their values, or creating new environment variables.
These variables are then:

inherited during a live upgrade
of an executable file;

used by the
ngx_http_perl_module module;

used by worker processes.
One should bear in mind that controlling system libraries in this way
is not always possible as it is common for libraries to check
variables only during initialization, well before they can be set
using this directive.
An exception from this is an above mentioned
live upgrade
of an executable file.

The TZ variable is always inherited and available to the
ngx_http_perl_module
module, unless it is configured explicitly.

Usage example:

env MALLOC_OPTIONS;
env PERL5LIB=/data/site/modules;
env OPENSSL_ALLOW_PROXY_CERTS=1;

The NGINX environment variable is used internally by nginx
and should not be set directly by the user.

            Syntax:

            error_log file [level]
[json];

            Default:

error_log logs/error.log error;

            Context:

            main, http, mail, stream, server, location

Configures logging.
Several logs can be specified on the same configuration level (1.5.2).
If on the main configuration level writing a log to a file
is not explicitly defined, the default file will be used.

The first parameter defines a file that will store the log.

The special value stderr selects the standard error file.
Logging to syslog can be configured by specifying
the “syslog:” prefix.
Logging to a
cyclic memory buffer
can be configured by specifying the “memory:” prefix and
buffer size, and is generally used for debugging (1.7.11).

The second parameter determines the level of logging,
and can be one of the following:
debug, info, notice,
warn, error, crit,
alert, or emerg.
Log levels above are listed in the order of increasing severity.
Setting a certain log level will cause all messages of
the specified and more severe log levels to be logged.
For example, the default level error will
cause error, crit,
alert, and emerg messages
to be logged.
If this parameter is omitted then error is used.

For debug logging to work, nginx needs to
be built with --with-debug,
see “A debugging log”.

The json parameter (1.29.8)
enables writing a log in the JSON format,
with support for
context tags:

{
  "level": "error",
  "timestamp": "2026-05-13T10:30:15.042+00:00",
  "pid": 12345,  "tid": 12345,  "cnum": 3,
  "msg": "connect() failed",
  "client": "192.168.1.10",  "server": "example.com",
  "request": "GET /api HTTP/1.1",
  "upstream": "http://127.0.0.1:8080/api",
  "errno": 111,
  "errtext": "Connection refused"
}

A log entry cannot exceed 2 KB,
data beyond this limit is truncated to “truncated”:1.
Debug logging is not supported for JSON.

This parameter is available as part of our
commercial subscription.

The directive can be specified on the
stream level
starting from version 1.7.11,
and on the mail level
starting from version 1.9.0.

            Syntax:

            events { ... }

            Default:

            —

            Context:

            main

Provides the configuration file context in which the directives that
affect connection processing are specified.

            Syntax:

            include file | mask;

            Default:

            —

            Context:

            any

Includes another file, or files matching the
specified mask, into configuration.
Included files should consist of
syntactically correct directives and blocks.

Usage example:

include mime.types;
include vhosts/*.conf;

            Syntax:

            load_module file;

            Default:

            —

            Context:

            main

This directive appeared in version 1.9.11.

Loads a dynamic module.

Example:

load_module modules/ngx_mail_module.so;

            Syntax:

            lock_file file;

            Default:

lock_file logs/nginx.lock;

            Context:

            main

nginx uses the locking mechanism to implement accept_mutex
and serialize access to shared memory.
On most systems the locks are implemented using atomic operations,
and this directive is ignored.
On other systems the “lock file” mechanism is used.
This directive specifies a prefix for the names of lock files.

            Syntax:

            master_process on | off;

            Default:

master_process on;

            Context:

            main

Determines whether worker processes are started.
This directive is intended for nginx developers.

            Syntax:

            multi_accept on | off;

            Default:

multi_accept off;

            Context:

            events

If multi_accept is disabled, a worker process
will accept one new connection at a time.
Otherwise, a worker process
will accept all new connections at a time.

The directive is ignored if kqueue
connection processing method is used, because it reports
the number of new connections waiting to be accepted.

            Syntax:

            pcre_jit on | off;

            Default:

pcre_jit off;

            Context:

            main

This directive appeared in version 1.1.12.

Enables or disables the use of “just-in-time compilation” (PCRE JIT)
for the regular expressions known by the time of configuration parsing.

PCRE JIT can speed up processing of regular expressions significantly.

The JIT is available in PCRE libraries starting from version 8.20
built with the --enable-jit configuration parameter.
When the PCRE library is built with nginx (--with-pcre=),
the JIT support is enabled via the
--with-pcre-jit configuration parameter.

            Syntax:

            pid file;

            Default:

pid logs/nginx.pid;

            Context:

            main

Defines a file that will store the process ID of the main process.

            Syntax:

            ssl_engine device;

            Default:

            —

            Context:

            main

Defines the name of the hardware SSL accelerator.

The module may be dynamically loaded by OpenSSL during configuration testing.

            Syntax:

            ssl_object_cache_inheritable on | off;

            Default:

ssl_object_cache_inheritable on;

            Context:

            main

This directive appeared in version 1.27.4.

If enabled, SSL objects
(SSL certificates, secret keys, trusted CA certificates, CRL lists)
will be inherited across configuration reloads.

SSL objects loaded from a file are inherited
if the modification time and file index has not been changed
since the previous configuration load.
Secret keys specified as
engine:name:id are never inherited.
Secret keys specified as
data:value are always inherited.

SSL objects loaded from variables cannot be inherited.

Example:

ssl_object_cache_inheritable on;

http {
    ...
    server {
        ...
        ssl_certificate     example.com.crt;
        ssl_certificate_key example.com.key;
    }
}

            Syntax:

            stall_threshold time;

            Default:

stall_threshold 1000ms;

            Context:

            events

This directive appeared in version 1.29.0.

Allows overriding the default time threshold for the event loop iteration
before a stall is reported.
By default, a stall is reported
when an event loop iteration exceeds 1000ms.
If the timer_resolution directive is enabled,
the time threshold will be ignored.

This directive is available as part of our
commercial subscription.

            Syntax:

            thread_pool
    name
    threads=number
    [max_queue=number];

            Default:

thread_pool default threads=32 max_queue=65536;

            Context:

            main

This directive appeared in version 1.7.11.

Defines the name and parameters of a thread pool
used for multi-threaded reading and sending of files
without blocking
worker processes.

The threads parameter
defines the number of threads in the pool.

In the event that all threads in the pool are busy,
a new task will wait in the queue.
The max_queue parameter limits the number
of tasks allowed to be waiting in the queue.
By default, up to 65536 tasks can wait in the queue.
When the queue overflows, the task is completed with an error.

            Syntax:

            timer_resolution interval;

            Default:

            —

            Context:

            main

Reduces timer resolution in worker processes, thus reducing the
number of gettimeofday() system calls made.
By default, gettimeofday() is called each time
a kernel event is received.
With reduced resolution, gettimeofday() is only
called once per specified interval.

Example:

timer_resolution 100ms;

Internal implementation of the interval depends on the method used:

the EVFILT_TIMER filter if kqueue is used;

timer_create() if eventport is used;

setitimer() otherwise.

            Syntax:

            use method;

            Default:

            —

            Context:

            events

Specifies the connection processing
method to use.
There is normally no need to specify it explicitly, because nginx will
by default use the most efficient method.

            Syntax:

            user user [group];

            Default:

user nobody nobody;

            Context:

            main

Defines user and group
credentials used by worker processes.
If group is omitted, a group whose name equals
that of user is used.

            Syntax:

            worker_aio_requests number;

            Default:

worker_aio_requests 32;

            Context:

            events

                    This directive appeared in versions 1.1.4 and 1.0.7.

When using aio
with the epoll
connection processing method, sets the maximum number of
outstanding asynchronous I/O operations
for a single worker process.

            Syntax:

            worker_connections number;

            Default:

worker_connections 512;

            Context:

            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.

            Syntax:

            worker_cpu_affinity cpumask ...;
worker_cpu_affinity auto [cpumask];

            Default:

            —

            Context:

            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,

worker_processes    4;
worker_cpu_affinity 0001 0010 0100 1000;

binds each worker process to a separate CPU, while

worker_processes    2;
worker_cpu_affinity 0101 1010;

binds the first worker process to CPU0/CPU2,
and the second worker process to CPU1/CPU3.
The second example is suitable for hyper-threading.

The special value auto (1.9.10) allows
binding worker processes automatically to available CPUs:

worker_processes auto;
worker_cpu_affinity auto;

The optional mask parameter can be used to limit the CPUs
available for automatic binding:

worker_cpu_affinity auto 01010101;

The directive is only available on FreeBSD and Linux.

            Syntax:

            worker_priority number;

            Default:

worker_priority 0;

            Context:

            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:

worker_priority -10;

            Syntax:

            worker_processes number | auto;

            Default:

worker_processes 1;

            Context:

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

The auto parameter is supported starting from
versions 1.3.8 and 1.2.5.

            Syntax:

            worker_rlimit_core size;

            Default:

            —

            Context:

            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.

            Syntax:

            worker_rlimit_nofile number;

            Default:

            —

            Context:

            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.

            Syntax:

            worker_shutdown_timeout time;

            Default:

            —

            Context:

            main

This directive appeared in version 1.11.11.

Configures a timeout for a graceful shutdown of worker processes.
When the time expires,
nginx will try to close all the connections currently open
to facilitate shutdown.

            Syntax:

            working_directory directory;

            Default:

            —

            Context:

            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.


<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Module ngx_google_perftools_module</title><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="../../css/style_en.css">

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

<input class="side-menu" type="checkbox" id="side-menu">

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.


<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Module ngx_mgmt_module</title><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="../../css/style_en.css">

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

<input class="side-menu" type="checkbox" id="side-menu">

english

русский

news

about

download

security

documentation

faq

books

community

enterprise

community forum (new)

x.com

blog

njs

ingress controller

gateway fabric

Module ngx_mgmt_module

Example Configuration
Directives
     mgmt
     enforce_initial_report
     license_token
     proxy
     proxy_username
     proxy_password
     resolver
     ssl_crl
     ssl_trusted_certificate
     ssl_verify
     state_path
     usage_report

The ngx_mgmt_module module enables
NGINX Plus license verification and usage reporting.
This is mandatory for each NGINX Plus instance since 1.27.2 (
NGINX Plus R33).

A JWT license file named license.jwt
should be located at
/etc/nginx/ for Linux or
/usr/local/etc/nginx/ for FreeBSD
or at the path specified by the license_token directive.
The license file is available from
MyF5.

Usage report is sent directly or via proxy
to F5 licensing endpoint
every hour using the
secure connection.
Optionally, in network-restricted environments
reporting can be configured to
F5 NGINX
Instance Manager from which the report can be sent
to F5 licensing endpoint.

By default, if the initial usage report
is not received by F5 licensing endpoint, nginx will stop processing traffic.

Automatic license renewal is supported since 1.29.0
(NGINX Plus R35)
for instances that report directly to the F5 licensing endpoint.
On renewal, NGINX downloads the updated JWT from F5 licensing endpoint
and applies it without
configuration reload.
The updated license is stored
in the state_path directory.

This module is available as part of our
commercial subscription.

Example Configuration

mgmt {
    # in case if custom path is required
    license_token custom/file/path/license.jwt;

    # in case of reporting to NGINX Instance Manager
    usage_report endpoint=NIM_FQDN;
}

Directives

            Syntax:

            mgmt { ... }

            Default:

            —

            Context:

            main

Provides the configuration file context in which
usage reporting and license management directives
are specified.

            Syntax:

            enforce_initial_report on | off;

            Default:

enforce_initial_report on;

            Context:

            mgmt

This directive appeared in version 1.27.2.

Enables or disables the 180-day grace period
for sending the initial usage report.

The initial usage report is sent immediately
upon nginx first start after installation.
By default, if the initial report is not received by F5 licensing endpoint,
nginx stops processing traffic until the report is successfully delivered.
Setting the directive value to off enables
the 180-day grace period during which
the initial usage report must be received by F5 licensing endpoint.

            Syntax:

            license_token file;

            Default:

license_token license.jwt;

            Context:

            mgmt

This directive appeared in version 1.27.2.

Specifies a JWT license file.
By default, the license.jwt file is expected to be at
/etc/nginx/ for Linux or at
/usr/local/etc/nginx/ for FreeBSD.

            Syntax:

            proxy host:port;

            Default:

            —

            Context:

            mgmt

This directive appeared in version 1.27.4.

Sets the HTTP CONNECT proxy
used for sending the usage report.

            Syntax:

            proxy_username string;

            Default:

            —

            Context:

            mgmt

This directive appeared in version 1.27.4.

Sets the user name used for authentication on
the proxy.

            Syntax:

            proxy_password string;

            Default:

            —

            Context:

            mgmt

This directive appeared in version 1.27.4.

Sets the password used for authentication on
the proxy.

The password is sent unencrypted by default.
If the proxy supports TLS, the connection to the proxy can be
protected with the stream
module:

mgmt {
    proxy          127.0.0.1:8080;
    proxy_username <name>;
    proxy_password <password>;
}

stream {
    server {
        listen 127.0.0.1:8080;

        proxy_ssl                     on;
        proxy_ssl_verify              on;
        proxy_ssl_trusted_certificate <proxy_ca_file>;

        proxy_pass <proxy_host>:<proxy_port>;
    }
}

            Syntax:

            resolver
    address ...
    [valid=time]
    [ipv4=on|off]
    [ipv6=on|off]
    [status_zone=zone];

            Default:

            —

            Context:

            mgmt

Configures name servers used to resolve usage reporting endpoint name.
By default, the system resolver is used.

See resolver for details.

            Syntax:

            ssl_crl file;

            Default:

            —

            Context:

            mgmt

Specifies a file with revoked certificates (CRL)
in the PEM format used to verify
the certificate of the usage reporting endpoint.
When using intermediate certificates, their CRLs should be
specified in the same file.

            Syntax:

            ssl_trusted_certificate file;

            Default:

ssl_trusted_certificate system CA bundle;

            Context:

            mgmt

Specifies a file with trusted CA certificates in the PEM format
used to verify
the certificate of the usage reporting endpoint.

            Syntax:

            ssl_verify on | off;

            Default:

ssl_verify on;

            Context:

            mgmt

Enables or disables verification of the usage reporting endpoint certificate.

Before 1.27.2, the default value was off.

            Syntax:

            state_path path;

            Default:

            —

            Context:

            mgmt

This directive appeared in version 1.27.2.

Defines a directory for storing state files
(nginx-mgmt-*)
created by the ngx_mgmt_module module.
The default directory
for Linux is /var/lib/nginx/state,
for FreeBSD is /var/db/nginx/state.

            Syntax:

            usage_report  [endpoint=address]
         [interval=time];

            Default:

usage_report endpoint=product.connect.nginx.com interval=1h;

            Context:

            mgmt

Sets the address and port
of the usage reporting endpoint.
The interval parameter sets an interval between
two consecutive reports.

Before 1.27.2, the default values were
nginx-mgmt.local and
30m.


<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Module ngx_otel_module</title><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="../../css/style_en.css">

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

<input class="side-menu" type="checkbox" id="side-menu">

english

русский

news

about

download

security

documentation

faq

books

community

enterprise

community forum (new)

x.com

blog

njs

ingress controller

gateway fabric

Module ngx_otel_module

Example Configuration
Directives
     otel_exporter
     otel_service_name
     otel_resource_attr
     otel_trace
     otel_trace_context
     otel_span_name
     otel_span_attr
Default span attributes
Embedded Variables

The ngx_otel_module module provides
OpenTelemetry
distributed tracing support.
The module supports
W3C
context propagation and OTLP/gRPC export protocol.

The source code of the module is available
here.
Download and install instructions are available
here.

The module is also available in a prebuilt
nginx-module-otel
package
since 1.25.3
and in nginx-plus-module-otel package
as part of our
commercial subscription since 1.23.4.

Example Configuration

load_module modules/ngx_otel_module.so;

events {
}

http {

    otel_exporter {
        endpoint localhost:4317;
    }

    server {
        listen 127.0.0.1:8080;

        location / {
            otel_trace         on;
            otel_trace_context inject;

            proxy_pass http://backend;
        }
    }
}

Directives

            Syntax:

            otel_exporter { ... }

            Default:

            —

            Context:

            http

Specifies OTel data export parameters:

    endpoint [(http|https)://]host:port;

OTLP/gRPC endpoint that will accept telemetry data.
TLS is supported since 0.1.2.

    trusted_certificate path;

the CA certificates file in PEM format used to verify TLS endpoint
(since 0.1.2).
Defaults to OS provided CA bundle.

header name value;

a custom HTTP header to add to telemetry export request (since 0.1.2).

interval time;

the maximum interval between two exports,
by default is 5 seconds.

batch_size number;

the maximum number of spans to be sent in one batch per worker,
by default is 512.

batch_count number;

the number of pending batches per worker,
spans exceeding the limit are dropped,
by default is 4.

Example:

otel_exporter {
    endpoint https://otel-example.nginx.com:4317;

    header X-API-Token "my-token-value";
}

            Syntax:

            otel_service_name name;

            Default:

otel_service_name unknown_service:nginx;

            Context:

            http

Sets the
“service.name”
attribute of the OTel resource.

            Syntax:

            otel_resource_attr name value;

            Default:

            —

            Context:

            http

This directive appeared in version 0.1.2.

Sets a custom OTel resource attribute.

            Syntax:

            otel_trace on |
        off |
        $variable;

            Default:

otel_trace off;

            Context:

            http, server, location

Enables or disables OpenTelemetry tracing.
The directive can also be enabled by specifying a variable:

split_clients "$otel_trace_id" $ratio_sampler {
              10%              on;
              *                off;
}

server {
    location / {
        otel_trace         $ratio_sampler;
        otel_trace_context inject;
        proxy_pass         http://backend;
    }
}

            Syntax:

            otel_trace_context extract |
        inject |
        propagate |
        ignore;

            Default:

otel_trace_context ignore;

            Context:

            http, server, location

Specifies how to propagate
traceparent/tracestate headers:

extract

uses an existing trace context from the request,
so that the identifiers of
a trace and
the parent span
are inherited from the incoming request.

inject

adds a new context to the request, overwriting existing headers, if any.

propagate

updates the existing context
(combines extract and inject).

ignore

skips context headers processing.

            Syntax:

            otel_span_name name;

            Default:

            —

            Context:

            http, server, location

Defines the name of the OTel
span.
By default, it is a name of the location for a request.
The name can contain variables.

            Syntax:

            otel_span_attr name value;

            Default:

            —

            Context:

            http, server, location

Adds a custom OTel span attribute.
The value can contain variables.

Default span attributes

The following
span
attributes
are added automatically:

http.method

http.target

http.route

http.scheme

http.flavor

http.user_agent

http.request_content_length

http.response_content_length

http.status_code

net.host.name

net.host.port

net.sock.peer.addr

net.sock.peer.port

Embedded Variables

$otel_trace_id

the identifier of the trace the current span belongs to,
for example, 56552bc4daa3bf39c08362527e1dd6c4

$otel_span_id

the identifier of the current span,
for example, 4c0b8531ec38ca59

$otel_parent_id

the identifier of the parent span,
for example, dc94d281b0f884ea

$otel_parent_sampled

the “sampled” flag of the parent span,
can be “1” or “0”


<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Support for QUIC and HTTP/3</title><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="../../css/style_en.css">

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

<input class="side-menu" type="checkbox" id="side-menu">

english

русский

news

about

download

security

documentation

faq

books

community

enterprise

community forum (new)

x.com

blog

njs

ingress controller

gateway fabric

Support for QUIC and HTTP/3

Building from sources
Configuration tips
Troubleshooting

Support for
QUIC
and
HTTP/3
protocols is available since 1.25.0, it is included in
Linux binary packages.
Please refer to the
ngx_http_v3_module
documentation.

Building from sources

The build is configured using the configure command.
Please refer to Building nginx from Sources for details.

The OpenSSL library
version 3.5.1 or higher is recommended to build nginx with QUIC support.
Otherwise, the OpenSSL
compatibility layer will be used that does not support
early data.
Alternatively,
BoringSSL,
LibreSSL, or
QuicTLS
prebuilt libraries can be used.

Use the following command to configure nginx with
BoringSSL:

./configure
    --with-debug
    --with-http_v3_module
    --with-cc-opt="-I../boringssl/include"
    --with-ld-opt="-L../boringssl/build -lstdc++"

Alternatively, nginx can be configured with
QuicTLS:

./configure
    --with-debug
    --with-http_v3_module
    --with-cc-opt="-I../quictls/build/include"
    --with-ld-opt="-L../quictls/build/lib"

Alternatively, nginx can be configured with
LibreSSL:

./configure
    --with-debug
    --with-http_v3_module
    --with-cc-opt="-I../libressl/build/include"
    --with-ld-opt="-L../libressl/build/lib"

After configuration,
nginx is compiled and installed using make.

Configuration tips

The listen directive in
ngx_http_core_module
module got a new parameter
quic
which enables HTTP/3 over QUIC on the specified port.

Along with the quic parameter
it is also possible to specify the
reuseport
parameter to make it work properly with multiple workers.

To enable
address validation:

quic_retry on;

To enable
0-RTT:

ssl_early_data on;

To enable
GSO (Generic Segmentation Offloading):

quic_gso on;

To set
host key for various tokens:

quic_host_key <filename>;

QUIC requires TLSv1.3 protocol version which is enabled by default
in the ssl_protocols directive.

By default,
GSO Linux-specific optimization
is disabled.
Enable it in case a corresponding network interface is configured
to support GSO.

Troubleshooting

Tips that may help to identify problems:

Ensure nginx is built with the proper SSL library.

Ensure nginx is using the proper SSL library in runtime
(the nginx -V shows what it is currently used).

Ensure a client is actually sending requests over QUIC.
It is recommended to start with a simple console client such as
ngtcp2
to ensure the server is configured properly before trying
with real browsers that may be quite picky with certificates.

Build nginx with debug support
and check the debug log.
It should contain all details about the connection and why it failed.
All related messages contain the “quic” prefix
and can be easily filtered out.

For a deeper investigation, additional debugging can be enabled
using the following macros:
NGX_QUIC_DEBUG_PACKETS,
NGX_QUIC_DEBUG_FRAMES,
NGX_QUIC_DEBUG_ALLOC,
NGX_QUIC_DEBUG_CRYPTO.

./configure
    --with-http_v3_module
    --with-debug
    --with-cc-opt="-DNGX_QUIC_DEBUG_PACKETS -DNGX_QUIC_DEBUG_CRYPTO"


<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Command-line parameters</title><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="../../css/style_en.css">

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

<input class="side-menu" type="checkbox" id="side-menu">

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.


<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Configuration file measurement units</title><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="../../css/style_en.css">

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

<input class="side-menu" type="checkbox" id="side-menu">

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.


<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Logging to syslog</title><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="../../css/style_en.css">

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

<input class="side-menu" type="checkbox" id="side-menu">

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.


<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>A message “ ‘sys_errlist’                 is deprecated;                 use ‘strerror’ or ‘strerror_r’                 instead ”</title><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="../../css/style_en.css">

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

<input class="side-menu" type="checkbox" id="side-menu">

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.


<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Alphabetical index of variables</title><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="../../css/style_en.css">

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

<input class="side-menu" type="checkbox" id="side-menu">

english

русский

news

about

download

security

documentation

faq

books

community

enterprise

community forum (new)

x.com

blog

njs

ingress controller

gateway fabric

Alphabetical index of variables

      $acme_certificate
$acme_certificate_key
$ancient_browser
$arg_
$args
$binary_remote_addr (ngx_http_core_module)
$binary_remote_addr (ngx_stream_core_module)
$body_bytes_sent
$bytes_received
$bytes_sent (ngx_http_core_module)
$bytes_sent (ngx_http_log_module)
$bytes_sent (ngx_stream_core_module)
$connection (ngx_http_core_module)
$connection (ngx_http_log_module)
$connection (ngx_stream_core_module)
$connection_requests (ngx_http_core_module)
$connection_requests (ngx_http_log_module)
$connection_time
$connections_active
$connections_reading
$connections_waiting
$connections_writing
$content_length
$content_type
$cookie_
$date_gmt
$date_local
$document_root
$document_uri
$fastcgi_path_info
$fastcgi_script_name
$geoip_area_code (ngx_http_geoip_module)
$geoip_area_code (ngx_stream_geoip_module)
$geoip_city (ngx_http_geoip_module)
$geoip_city (ngx_stream_geoip_module)
$geoip_city_continent_code (ngx_http_geoip_module)
$geoip_city_continent_code (ngx_stream_geoip_module)
$geoip_city_country_code (ngx_http_geoip_module)
$geoip_city_country_code (ngx_stream_geoip_module)
$geoip_city_country_code3 (ngx_http_geoip_module)
$geoip_city_country_code3 (ngx_stream_geoip_module)
$geoip_city_country_name (ngx_http_geoip_module)
$geoip_city_country_name (ngx_stream_geoip_module)
$geoip_country_code (ngx_http_geoip_module)
$geoip_country_code (ngx_stream_geoip_module)
$geoip_country_code3 (ngx_http_geoip_module)
$geoip_country_code3 (ngx_stream_geoip_module)
$geoip_country_name (ngx_http_geoip_module)
$geoip_country_name (ngx_stream_geoip_module)
$geoip_dma_code (ngx_http_geoip_module)
$geoip_dma_code (ngx_stream_geoip_module)
$geoip_latitude (ngx_http_geoip_module)
$geoip_latitude (ngx_stream_geoip_module)
$geoip_longitude (ngx_http_geoip_module)
$geoip_longitude (ngx_stream_geoip_module)
$geoip_org (ngx_http_geoip_module)
$geoip_org (ngx_stream_geoip_module)
$geoip_postal_code (ngx_http_geoip_module)
$geoip_postal_code (ngx_stream_geoip_module)
$geoip_region (ngx_http_geoip_module)
$geoip_region (ngx_stream_geoip_module)
$geoip_region_name (ngx_http_geoip_module)
$geoip_region_name (ngx_stream_geoip_module)
$gzip_ratio
$host
$hostname (ngx_http_core_module)
$hostname (ngx_stream_core_module)
$http2
$http3
$http_
$https
$invalid_referer
$is_args
$is_request_port
$jwt_claim_
$jwt_header_
$jwt_payload
$limit_conn_status (ngx_http_limit_conn_module)
$limit_conn_status (ngx_stream_limit_conn_module)
$limit_rate
$limit_req_status
$memcached_key
$modern_browser
$mqtt_preread_clientid
$mqtt_preread_username
$msec (ngx_http_core_module)
$msec (ngx_http_log_module)
$msec (ngx_stream_core_module)
$msie
$nginx_version (ngx_http_core_module)
$nginx_version (ngx_stream_core_module)
$oidc_access_token
$oidc_claim_
$oidc_id_token
$oidc_userinfo
$otel_parent_id
$otel_parent_sampled
$otel_span_id
$otel_trace_id
$pid (ngx_http_core_module)
$pid (ngx_stream_core_module)
$pipe (ngx_http_core_module)
$pipe (ngx_http_log_module)
$protocol
$proxy_add_x_forwarded_for
$proxy_host
$proxy_port
$proxy_protocol_addr (ngx_http_core_module)
$proxy_protocol_addr (ngx_stream_core_module)
$proxy_protocol_port (ngx_http_core_module)
$proxy_protocol_port (ngx_stream_core_module)
$proxy_protocol_server_addr (ngx_http_core_module)
$proxy_protocol_server_addr (ngx_stream_core_module)
$proxy_protocol_server_port (ngx_http_core_module)
$proxy_protocol_server_port (ngx_stream_core_module)
$proxy_protocol_tlv_ (ngx_http_core_module)
$proxy_protocol_tlv_ (ngx_stream_core_module)
$proxy_protocol_tlv_aws_vpce_id (ngx_http_proxy_protocol_vendor_module)
$proxy_protocol_tlv_aws_vpce_id (ngx_stream_proxy_protocol_vendor_module)
$proxy_protocol_tlv_azure_pel_id (ngx_http_proxy_protocol_vendor_module)
$proxy_protocol_tlv_azure_pel_id (ngx_stream_proxy_protocol_vendor_module)
$proxy_protocol_tlv_gcp_conn_id (ngx_http_proxy_protocol_vendor_module)
$proxy_protocol_tlv_gcp_conn_id (ngx_stream_proxy_protocol_vendor_module)
$query_string
$realip_remote_addr (ngx_http_realip_module)
$realip_remote_addr (ngx_stream_realip_module)
$realip_remote_port (ngx_http_realip_module)
$realip_remote_port (ngx_stream_realip_module)
$realpath_root
$remote_addr (ngx_http_core_module)
$remote_addr (ngx_stream_core_module)
$remote_port (ngx_http_core_module)
$remote_port (ngx_stream_core_module)
$remote_user
$request
$request_body
$request_body_file
$request_completion
$request_filename
$request_id
$request_length (ngx_http_core_module)
$request_length (ngx_http_log_module)
$request_method
$request_port
$request_time (ngx_http_core_module)
$request_time (ngx_http_log_module)
$request_uri
$scheme
$secure_link
$secure_link_expires
$sent_http_
$sent_trailer_
$server_addr (ngx_http_core_module)
$server_addr (ngx_stream_core_module)
$server_name
$server_port (ngx_http_core_module)
$server_port (ngx_stream_core_module)
$server_protocol
$session_log_binary_id
$session_log_id
$session_time
$slice_range
$ssl_alpn_protocol (ngx_http_ssl_module)
$ssl_alpn_protocol (ngx_stream_ssl_module)
$ssl_cipher (ngx_http_ssl_module)
$ssl_cipher (ngx_stream_ssl_module)
$ssl_ciphers (ngx_http_ssl_module)
$ssl_ciphers (ngx_stream_ssl_module)
$ssl_client_cert (ngx_http_ssl_module)
$ssl_client_cert (ngx_stream_ssl_module)
$ssl_client_escaped_cert
$ssl_client_fingerprint (ngx_http_ssl_module)
$ssl_client_fingerprint (ngx_stream_ssl_module)
$ssl_client_i_dn (ngx_http_ssl_module)
$ssl_client_i_dn (ngx_stream_ssl_module)
$ssl_client_i_dn_legacy
$ssl_client_raw_cert (ngx_http_ssl_module)
$ssl_client_raw_cert (ngx_stream_ssl_module)
$ssl_client_s_dn (ngx_http_ssl_module)
$ssl_client_s_dn (ngx_stream_ssl_module)
$ssl_client_s_dn_legacy
$ssl_client_serial (ngx_http_ssl_module)
$ssl_client_serial (ngx_stream_ssl_module)
$ssl_client_sigalg (ngx_http_ssl_module)
$ssl_client_sigalg (ngx_stream_ssl_module)
$ssl_client_v_end (ngx_http_ssl_module)
$ssl_client_v_end (ngx_stream_ssl_module)
$ssl_client_v_remain (ngx_http_ssl_module)
$ssl_client_v_remain (ngx_stream_ssl_module)
$ssl_client_v_start (ngx_http_ssl_module)
$ssl_client_v_start (ngx_stream_ssl_module)
$ssl_client_verify (ngx_http_ssl_module)
$ssl_client_verify (ngx_stream_ssl_module)
$ssl_curve (ngx_http_ssl_module)
$ssl_curve (ngx_stream_ssl_module)
$ssl_curves (ngx_http_ssl_module)
$ssl_curves (ngx_stream_ssl_module)
$ssl_early_data
$ssl_ech_outer_server_name (ngx_http_ssl_module)
$ssl_ech_outer_server_name (ngx_stream_ssl_module)
$ssl_ech_status (ngx_http_ssl_module)
$ssl_ech_status (ngx_stream_ssl_module)
$ssl_preread_alpn_protocols
$ssl_preread_protocol
$ssl_preread_server_name
$ssl_protocol (ngx_http_ssl_module)
$ssl_protocol (ngx_stream_ssl_module)
$ssl_server_name (ngx_http_ssl_module)
$ssl_server_name (ngx_stream_ssl_module)
$ssl_session_id (ngx_http_ssl_module)
$ssl_session_id (ngx_stream_ssl_module)
$ssl_session_reused (ngx_http_ssl_module)
$ssl_session_reused (ngx_stream_ssl_module)
$ssl_sigalg (ngx_http_ssl_module)
$ssl_sigalg (ngx_stream_ssl_module)
$status (ngx_http_core_module)
$status (ngx_http_log_module)
$status (ngx_stream_core_module)
$tcpinfo_rtt
$tcpinfo_rttvar
$tcpinfo_snd_cwnd
$tcpinfo_rcv_space
$time_iso8601 (ngx_http_core_module)
$time_iso8601 (ngx_http_log_module)
$time_iso8601 (ngx_stream_core_module)
$time_iso8601_ms (ngx_http_core_module)
$time_iso8601_ms (ngx_stream_core_module)
$time_local (ngx_http_core_module)
$time_local (ngx_http_log_module)
$time_local (ngx_stream_core_module)
$uid_got
$uid_reset
$uid_set
$upstream_addr (ngx_http_upstream_module)
$upstream_addr (ngx_stream_upstream_module)
$upstream_bytes_received (ngx_http_upstream_module)
$upstream_bytes_received (ngx_stream_upstream_module)
$upstream_bytes_sent (ngx_http_upstream_module)
$upstream_bytes_sent (ngx_stream_upstream_module)
$upstream_cache_status
$upstream_connect_time (ngx_http_upstream_module)
$upstream_connect_time (ngx_stream_upstream_module)
$upstream_cookie_
$upstream_first_byte_time
$upstream_header_time
$upstream_http_
$upstream_last_addr (ngx_http_upstream_module)
$upstream_last_addr (ngx_stream_upstream_module)
$upstream_last_server_name
$upstream_queue_time
$upstream_response_length
$upstream_response_time
$upstream_session_time
$upstream_status
$upstream_trailer_
$uri