Question 1

Why does 'nginx -s stop' fail to stop the server when the configuration file is invalid?

Accepted Answer

nginx validates the configuration even for '-s stop', so it refuses to stop if there are errors. As a workaround, use systemctl stop nginx (systemd), or send a QUIT signal directly to the nginx master process (e.g., kill -QUIT $(cat /var/run/nginx.pid)). You can also temporarily fix the config file to allow a clean stop.

Question 2

Why does my custom NGINX stream module hang after a successful SSL handshake?

Accepted Answer

The standard `ngx_stream_ssl_init_connection()` returns `NGX_OK` after a successful handshake without calling the handshake handler because it is invoked from within the stream phase engine loop (`ngx_stream_core_run_phases`). The phase engine automatically continues to the next phase upon `NGX_OK`. If your custom module initiates the SSL handshake outside of this phase engine context, you must call `ngx_stream_core_run_phases(s)` or replicate the phase logic to avoid hanging.

Question 3

Why is the proxy_cache_key static when using $slice_range inside a set directive in NGINX?

Accepted Answer

The `set` directive evaluates complex values at assignment time, making `$cache_key` static for the main request. For slice module subrequests, `$slice_range` changes, but the cached value doesn’t reflect that. Workaround: Use `$slice_range` directly in `proxy_cache_key`, e.g., `proxy_cache_key "$uri:$slice_range";`. A patch or `volatile` parameter (like `map`) may be needed for lazy evaluation.

Question 4

Why does nginx ignore server_name when listening on both 0.0.0.0 and 127.0.0.1?

Accepted Answer

When nginx has multiple listen directives with the same port but different addresses, and one uses a wildcard (0.0.0.0), nginx groups servers by listen address. A more specific address (127.0.0.1) takes precedence, causing server_name comparison to be skipped. To fix this, add the bind parameter to the specific IP listen directive: `listen 127.0.0.1:80 bind;`. This forces a separate bind() call per address, allowing virtual host matching to work correctly. Alternatively, avoid mixing wildcard and specific addresses on the same port.

Question 5

Why do websocket connections fail when using HTTP/2 proxying in nginx?

Accepted Answer

HTTP/2 does not support the Upgrade header required for websocket bootstrapping. To proxy websockets, you must use HTTP/1.1. For nginx 1.21.6+, you can use a map on $http_upgrade to set proxy_http_version conditionally: `map $http_upgrade $proxy_http_version { default 2; "websocket" 1.1; }` and then `proxy_http_version $proxy_http_version;`. For older versions, define separate location blocks with `proxy_http_version 1.1` for websocket endpoints.

nginx

Core Features

What It Can't Do

Use Cases

Tags

Getting Started

Similar Projects