nginx 1.31.5's control API tur... Note

nginx 1.31.5's control API turns a failed reload into an HTTP 422 instead of a log line

Nginx version 1.31.5 introduced a new control API accessible via a Unix socket or TCP port. This API allows for HTTP-based reloads and provides structured responses, unlike the traditional signal-based reload method. It can be enabled with a command-line flag, and the official Docker image includes the necessary compilation. The API's endpoint tree can be discovered by making sequential GET requests. Key endpoints include /1/control/processes to get worker PIDs and /1/control/config to retrieve the live configuration. A PATCH request to /1/control/config triggers a configuration reload by re-reading the config file from disk. This API provides a significant advantage by returning a parsable JSON error message upon a failed reload, unlike the less informative signal method. Despite initial assumptions, the API reload process is not demonstrably faster than the signal method. Concurrency testing showed that in-flight requests are unaffected by reloads, regardless of the method used. The control API carries significant security risks if bound to a network port, as it lacks native authentication and can be exploited by anyone with network access. Binding the socket to a Unix socket with strict file permissions is the recommended mitigation, effectively blocking unprivileged users. Enabling the control socket incurs a small memory overhead for the master process. Testing revealed that host-side file edits to bind-mounted configuration files may not propagate to running containers, requiring methods like docker cp for immediate updates. The primary benefit of the control API lies in its superior error reporting during reloads, making it valuable for deployment scripts. It is strongly advised to bind the control socket only to a Unix socket with appropriate permissions. Administrators should audit systems for any network-bound control sockets on Nginx versions 1.31.5 and newer.